* The Business of Software

A former community discussing the business of software, from the smallest shareware operation to Microsoft. A part of Joel on Software.

We're closed, folks!

Links:

» Business of Software FAQ
» The Business of Software Conference (held every fall, usually in Boston)
» Forum guidelines (Please read before posting!)

Moderators:

Andy Brice
Successful Software

Doug Nebeker ("Doug")

Jonathan Matthews
Creator of DeepTrawl, CloudTrawl, and LeapDoc

Nicholas Hebb
BreezeTree Software

Bob Walsh
host, Startup Success Podcast author of The Web Startup Success Guide and Micro-ISV: From Vision To Reality

Patrick McKenzie
Bingo Card Creator

To comment the code or not

I have a unique situation where I work with a single programmer who wrote an entire commercial application plus a suite of utilities around it to support certain functions. I am the one who writes functional specs and most of the time the level architecture while he is the guy impementing it. Sometimes he hires subcontractor on freelancing sites to develop small modules, etc, but mainly he is the guy who knows the code. I am not a programmer and I never was. He loves writing code on the other hand and he did that since he was in high school but he never worked in a team of programmers or never lead a team programmers on a significant project over several years.
Now - I asked him several times to comment the code but he constantly refuses or avoids it more or less. His justification to this is that well structured code is worth well more than poorly written code that is commented and by having to add comments it would diminish its productivity by 20 % at least. The code is mainly vb.net and javascript.
Alternatively, I asked him to make references in the code to the issue # of the bugtracking system that we have wherever he implements a new function, etc.  My idea is that if we ever need to scale and hire more programmers (let alone if he ever gets hit by a bus and I need to to find someone to replace him without any handing over) or if we ever want to sell the business and the potential buyer would evaluate our technology by looking at how the codes is written, etc., then the code would be better to be commented. Right?
I don't believe he avoids to comment because of fear to be less indispensable (frankly I don't even imagine what would ve to replace him), I believe he is doing this by pure laziness or lack of understanding of the potential benefits.
To me as a non programmer is mind boggling of not having fully commented code and in a perfect world, the code would be 100% commented which obviously is not possible. But even if only 10 or 20 % is commented would probably be enough.
What do you think? Am I asking too much from him? 
Could you share some of your practical experiences on the subject?
And how can I convince him to do it?
StevenP Send private email
Friday, February 08, 2013
 
 
I for one always put comments in my code as it makes it easier to jump back into code that you wrote months/maybe years ago.
Could be that a certain module isn't touched for months and then when you need to change something it takes some refreshing the mind to get back into the logic.
Comments come in handy to add subtle remarks for certain special cases, explain what a function does,...

I also document my functions immediately and it's basically not much 'extra' work because I do it while coding. I consider it coding and don't even think about the fact that it's a comment.

Code also needs to be made descriptive so that you can easily read through it (good names for functions/variables/layout...) but still comments add a nice extra into clarifying things.

Just make sure that you find the right balance between the two and that the comments make sense; don't just add comments to have them either.

For you it's hard to judge the amount of comments/quality of code... he has written of course.

Maybe it wouldn't be bad to 'document' the architecture first; start with a high-level architecture of the product and its different modules.
Because this wil give an overview to new hires before they start delving in the code and see how the whole solution fits together.
Having documents on the architecture/components I for one think is a must to have and to start from.
Jeroen V Send private email
Friday, February 08, 2013
 
 
I think white space in code is better.
Harry Phace Send private email
Friday, February 08, 2013
 
 
Commenting in code where the purpose/meaning/method is not obvious; otherwise, nice formatting and if possible descriptive variable/method names so that the code is fairly self-documenting.  IMHO.
John Clark Send private email
Friday, February 08, 2013
 
 
As a programmer and a tech lead, I can see both sides of this.  I usually don't comment my code very much because I use descriptive naming, whitespace, etc... and having a comment with code like this is not helpful:

int counter; // a counter

//delete the file
File.Delete();

I will comment something that is tricky or if there was a reason for picking something that is not obvious so that myself or others can see it months later.

As for the adding comments for changes, I think that adding comments like that clutter the code alot.  The reason is, this like of code was changed for issue 15, and then issue 67, and then issue 92.  There is no telling what the original was or any of the changes.  I think that this is where a good source control system is a must for all developers.  This way you know that a new feature/task/issue is tied in with a certain change into the source code repository.  This way also having freelancers work on things means that a good online source control system would be a good thing as well.  This way you and your programmer, can write up the tasks, assign them, test them, and know what changes were involved in it.  I personally use TFS from Microsoft.  They have an online version that is free for up to 5 people and you can do all of the tasks, issues, etc that you want and have it tie into the source code when it is checked in.  Then you can run reports to see what was changed for the issues.  This goes way farther than commenting the code. 

http://tfs.visualstudio.com/
SteveM Send private email
Friday, February 08, 2013
 
 
For me, the code should be understandable/self-documenting in most cases. If it is in something like assembler, or even C, then maybe you need it, but most modern languages allow you to be quite expressive.

I do most of my work in SQL, C#, HTML and JavaScript and hardly ever add comments.

I know some places insist on comments in code, but that doesn't always add value, just like any other rigid rule.
Scorpio Send private email
Friday, February 08, 2013
 
 
The advice I give is:
Comment the areas you're proud of, and comment the areas you're ashamed of.
Generally these are the two areas where you'll have non-obvious code, and so a comment is a good reminder of what you did there.

On the other hand, I don't like comments in the code about bug fixes, because those get stale and misleading very quickly. I prefer referencing the code in the bug ticket itself, or if your version control system allows it, in the check-in notes. I'm curious why you think 100% commented code is a perfect state, however?

Sorry to say, but you're in a rough spot. The developer is both probably suspicious about you wanting to replace him, and he knows he has the power to ignore you and be lazy because it would be costly to replace him. Are you his manager?
Jarrett Lee Send private email
Friday, February 08, 2013
 
 
Thanks for the feedback so far.

@Jarrett
I like that, makes a lot of sense.
"Comment the areas you're proud of, and comment the areas you're ashamed of."

Again, I don't believe he's avoiding comments to protect his turf, he is a very smart guy by the way, I suspect he thinks any programmer is capable to understand his code at firs sight.
And I am not his manager, we are rather partners. But being the one more on the business side I want to make sure things stay relatively clean. It's a matter of trust after all - if he tells me comments are not needed if the code is clean I have to trust him.  Past experiences showed me that trusting someone 100% without a second opinion can be very dangerous. For example, I entrusted someone for a particular architecture / implementation although my sense was telling me that it was a bad idea and I didn't ask for any thorough  arguments either . Then as things progressed, it became obvious the idea wasn't really good and more thought and research would have saved us a lot of pain. No big deal, but since coding is not what I do it's hard for me to estimate the impact of such a miss - I mean comments in the code.

And no, I don't believe that 100% commented code is good - I meant to say having code that is rigorously commented everywhere it should be and where it makes sense it's better than not having it commented.

Again - I'm not trying to discipline someone for the sake of following best practices, blah, blah, blah.
I imagine comments are needed if I come to you (you=programmer) and tell you -
"hey, I got this monster app here that we've written for past x years, the previous guy is gone, I can tell you what the app is supposed to do but I have no idea what that variable means or what this function does.
I don't know how clean the actual code is - the previous guy told me it's very clean so no need for comments."

The question is - do you need any comments to be able to carry on the task without spending three months just looking at the code?

I guess I should take the code on a USB stick an show it to one or two other people and ask them if they can understand it and work with it.
StevenP Send private email
Friday, February 08, 2013
 
 
I have trouble understanding the idea of not commenting *AT ALL*.  I see comments as a form of documentation.  Sure, any code that runs, whether well-structured or pure spaghetti, with enough time and effort, be made sense of.  But why would you not make use of this incredible tool of just putting human natural language clues into the code itself here and there? 

While you're here--Does he follow other good coding conventions for readability. such as found:

http://net.tutsplus.com/tutorials/html-css-techniques/top-15-best-practices-for-writing-super-readable-code/

(Note the #1 best practice, btw).

Oh and, regarding trust:  ** "Trust but verify."  **
Racky Send private email
Friday, February 08, 2013
 
 
There's a religious cult based around not commenting as the right thing to do.

Of course it's not but it's a convenient religion to adopt as it allows one to be lazy and undisciplined and call it a moral choice.

You can't win religious wars though.

So you tell this guy start writing good comments, perhaps of each function or each module.

If he won't then you get someone else.

If you can't get someone else then you accept whatever this guy gives you and pay whatever he asks because you don't have choices.

Perhaps you hire someone from high school or a college student $20/hr to refactor and organize the code and add comments. That might work.
Scott Send private email
Friday, February 08, 2013
 
 
"I am not his manager, we are rather partners."

Oh that's different. Don't tell me this is another one of those terrible situations where you are the idea man and he is there to implement it for equity while you sit around badgering him.
Scott Send private email
Friday, February 08, 2013
 
 
Since that's obviously the case I have new advice.

He should fire you and go it alone with his code, the code he wrote and owns and can comment as he pleases.

You're not paying the guy - he owes you nothing.
Scott Send private email
Friday, February 08, 2013
 
 
I've always loved this quote (but I don't follow it):

"Why should I comment my code?  It was hard to write; it should be hard to read!"

Don't know who wrote it, but I love it.  :)
Harry Phace Send private email
Saturday, February 09, 2013
 
 
@ Harry Potter
"Why should I comment my code?  It was hard to write; it should be hard to read!" Don't know who wrote it, but I love it.  :) "

I wrote that
alexandar Send private email
Saturday, February 09, 2013
 
 
There is a very good case to be made for limiting comments in your code.  In Clean Code, Robert Fowler has a chapter on comments:
"Nothing can be quite so helpful as a well placed comment.  Nothing can clutter up a module more than frivolous dogmatic comments.  Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.
Comments are not like Schindler's List.  They are not "pure good."  Indeed, comments are, at best, a necessary evil.  If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we should not need comments very much - perhaps not at all"
Chris Newey Send private email
Saturday, February 09, 2013
 
 
This is one of those threads where I had an opinion before reading and a different opinion after...

(I thought commenting was important)





AC
Reluctantlyregistered Send private email
Sunday, February 10, 2013
 
 
>> "I thought commenting was important"


It is.
Wyatt O'Day Send private email
Sunday, February 10, 2013
 
 
Just for a moment let's call it what it is - documentation.

Comments are one of the types of documentation of code.

Should Microsoft Word not provide a user manual? Should they remove the Help system?

After all Microsoft has expressive usability experts who have created Word with the goal of ease of use in mind, so documentation should not be necessary.

Now the user interface has been designed for usability. Despite their best efforts it is possible though that some features may not be intuitive and obvious how to find, configure, use and master.

What about code? Code is not generally written with usability in mind, so it is going to be harder to understand than it is for the user to understand the feature. Should the code also not be documented?
Scott Send private email
Sunday, February 10, 2013
 
 
I've never heard of good, well structured software not having comments.

Are you telling me there is nothing complex or tricky in the implementation ? That all the software is so trivial that every step and concept can easily fit into your partner's head ? I didn't think so.

Lack of comments is a "bad code smell" IMHO.

You don't need comments on every line, but you need comments where appropriate. Unless we are talking trivial getter/setter functions then you need a comment for every function that says what the function *intends to do*.

Adding reference numbers to the bug tracker is only useful if you have to do something unexpected to fix the problem or you came up with a counter intuitive solution; in which case you reference the bug tracker where you have stored the arguments and discussion for various other solutions.

It seems to me that you have the luxury of two people to have a proper system. One to write the functional spec and one to implement it. But this is open loop, unless the spec writer also takes some part in testing that the software does what was intended and writes the user documentation.

In summary, your partner should be commenting the code and you should be taking some responsibility for the end part of the documentation process.
koan Send private email
Sunday, February 10, 2013
 
 
If it's clear by reading the code what you are doing then comments are redundant at best.  If it's not clear, re-write the code until it is!  If that's not possible then add some comments but be aware that there is no more confusing situation than a complicated block of code with comments that are out of sync with changes.
Chris Newey Send private email
Monday, February 11, 2013
 
 
This guys has it right:
http://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/

And I respectfully disagree with Scott that programmers align themselves with the "cult" no non-coders out of laziness.  This is patently silly because it takes considerably more effort to write clean and understandable code than it does to leave a ball of mud with a few lines of comments explaining what you were trying to do.
Chris Newey Send private email
Monday, February 11, 2013
 
 
1) I have seen too many pieces of code where a one- or two-line comment would have saved me a couple hours of having to dig into the code and still not be totally sure.  I have very little patience for uncommented code.

2) Many of my comments deal with *why* something is being done.

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Monday, February 11, 2013
 
 
>  This is patently silly because it takes considerably more effort to write clean and understandable code than it does to leave a ball of mud with a few lines of comments explaining what you were trying to do.

Well  technically that's a false dichotomy. It's not been shown that there's a correlation between well designed comments and badly designed code, and between poor comments and good code. Lacking such a study, it makes more sense to assume the opposite, that good design either permeates the project or it doesn't.
Scott Send private email
Monday, February 11, 2013
 
 
I was responding to this:

>Of course it's not but it's a convenient religion to adopt as it allows one to be lazy and undisciplined and call it a moral choice.

I guess if you're lazy then you are not going to comment and you will write poor code, sure.  However, I think it's been shown that not littering your code with useless noise and not applying dogmatic rules (ie every function/module shall be commented) is actually a very sensible and pragmatic thing to do. 

And Gene, I don't thing anyone has said you shouldn't add any comments at all.  Only that they should be used sparingly and only where absolutely necessary.
Chris Newey Send private email
Monday, February 11, 2013
 
 
"that good design either permeates the project or it doesn't."
Words to live by, seriously.  "Test everything.  Hold onto the good." 1
Thessalonians 5:21
Howard Ness Send private email
Monday, February 11, 2013
 
 
I agree Howard; and lines upon lines of comments strewn all over the codebase is not indicative of good design.  Quite the opposite IMO.
Chris Newey Send private email
Monday, February 11, 2013
 
 
If you have no comments at all in an entire module, then yeah you're an idiot and shouldn't be coding. However such abysmal practice is common, the average person calling themselves a developer contributes nothing to society. We're not joking when we say the best are ten times better than average, except that the best are actually a thousand times better than average.
Scott Send private email
Monday, February 11, 2013
 
 
Silly strawman arguments and diatribes aside, I'm not sure what the disagreement is.  It is not exactly a controversial statement that comments are a necessary evil.  If we are to take our work seriously, then our goal is to write the most clear code possible.  Very focused functions, well-named variables, adhering to the SRP, and rigorously refactoring our code can help make comments superfluous.
I'm not saying one should never add comments, nothing of the sort.  However, they should be added judiciously, only when the intent of the code is not obvious and we don't have the ability to make it obvious.

"If the code is so complicated that it needs to be explained, it's nearly always better to improve the code than it is to add comments.." - Steve McConnell, Code Complete
Chris Newey Send private email
Tuesday, February 12, 2013
 
 
Chris Newey: "And Gene, I don't thing anyone has said you shouldn't add any comments at all.  Only that they should be used sparingly and only where absolutely necessary."

Why?  Is there a shortage of words?

I comment each of my procedures.

I typically have a header comment with name of procedure, descriptive name of procedure, and date last modified.  Each of these is one line.  The header comments serve as separator making it easy to find each procedure.

I comment each of the parameters.  Type is not sufficient.  It is all-too-easy to have a special value.  For example, in a client billing app that I maintain, some procedures have a client code parameter.  In some cases, a blank client code means to process for all clients.  I document this sort of thing.  If the language does not have explicit types, I document the type.  These comments are typically line comments; they need not be lengthy.

If the procedure returns a value, I document that.

If there are special considerations/preconditions, I document that.

After this, if there are other points that could benefit from a comment, I add one.

I document SQL create table statements heavily.  These are the reference for what the table means so I put a full definition of what the valid values are and what each means.

This really is not a great deal of commenting.  Many of these are brief, but they sure save time when I look at the code later.  For the client billing app I referred to, it can be years between changes.  In one case, it was 14 years, 3 days.

The problem with "absolutely necessary" is that you often find out only after you need the documentation.

You can spend more time arguing about it than simply doing it.

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Tuesday, February 12, 2013
 
 
>Why?  Is there a shortage of words?

No, it's because each comment carries with it a risk. 

First of all commenting out of sheer rote is, well, a waste of time:

//return order with id = id
public Order GetOrderById(int id)
{
      return _orders.FirstOrDefault(o=>o.Id == id);
}

Second, if comments are used everywhere, needed or not such as before every class, they tend to not add any value and are ignored or glossed over.  These types of comments do nothing but add noise to your code.

Third, there are no compiler checks and no tests that can verify comments.  If you are worried about lazy programmers just wait until one modifies your code base but does not update the comments. 

/*
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}

Believe me, misleading comments are an order of magnitude worse than no comments at all.  And let's be honest, you don't have to be a slug programmer to forget to update a comment.

FWIW, here's Jeff Atwood's take on the subject:
http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
Chris Newey Send private email
Tuesday, February 12, 2013
 
 
Gene Wirchenko: Why?  Is there a shortage of words?

Chris Newey: "No, it's because each comment carries with it a risk."

So does writing code, and we still do that.

"First of all commenting out of sheer rote is, well, a waste of time:

//return order with id = id
public Order GetOrderById(int id)
{
      return _orders.FirstOrDefault(o=>o.Id == id);
}"

I find the heading very useful for identifying where a procedure starts.  The title line often documents what the procedure does at a high level.  Sometimes, that is all the documentation required.  The date modified lets me know when the code was last worked on.  This is useful in bug tracking.

"Second, if comments are used everywhere, needed or not such as before every class, they tend to not add any value and are ignored or glossed over.  These types of comments do nothing but add noise to your code."

When I look at code that is not commented, I do not know where to start.  A comment about what a class is for helps me decide whether it is the right one to use.

"Third, there are no compiler checks and no tests that can verify comments.  If you are worried about lazy programmers just wait until one modifies your code base but does not update the comments.

/*
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}"

So the problem is not so much comments but lazy programmers.  If someone is out to sabotage, he will do it anyway.

"Believe me, misleading comments are an order of magnitude worse than no comments at all.  And let's be honest, you don't have to be a slug programmer to forget to update a comment."

Sure.  Actually, getting into the habit of commenting makes it easy to remember.

"FWIW, here's Jeff Atwood's take on the subject:
http://www.codinghorror.com/blog/2008/07/coding-without-comments.html"

Ah, yes, self-documenting code.  There is the pithy remark about that: "Self-documenting code isn't."  I have seen plenty of code that I have had to spend much too much time on figuring out what it did.  If there is the possibility of bug, knowing what the intent was does help.  Code only states what to do. It does not say why.

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Wednesday, February 13, 2013
 
 
Do you think it is a good idea to start a company that builds skyscrapers if you don't know anything about construction?  Or to open a private Heart Surgery clinic if you don't know anything about doing surgery? 

If you answered no to either of those questions.  Than your answer to the question should a software executive know how to program should be ....ABSOLUTELY.

Programming is not that difficult to learn.  You don't have to become an expert.  Get a book on programming, go through the whole thing, and do all the excercises.

It will be a fun challenge.  I think the problem might be you, not him.  What if you hire 10 people.  How do you expect to help manage a team that does something you don't understand?  A few comments in the code won't change the fact that the boss doesn't know what the workers are doing.

About the comments.  I agree with your partner.  And I imagine he might just be a bit peeved at you for second guessing his work.

Consider this function: 

Void PredictUserVote() {
    if (userIsOnWelfare == true)
        user.votePrediction = barackObama;
    else
        user.votePrediction = mittRomney;
}

Does that need a comment?  It is entirely possible to write an entire program this descriptively. 

Not only is that easy to understand.  It is easy to figure out how to change, modify, and expand.  Here is the same code with a comment but without descriptive names:

// This is the function that predicts the user vote

Void PrdctnFunc{
if (user.pblcAsst == 1)
    user.vt = 0;
else
    user.vt = 1;
}

It is a mess and it would take another 5 comments to explain everything then if I want to change something, I need to change all of the comments.  And if three people worked on it, it would just get to the point where it eventually becomes a bug that pisses off your customers.


It also seems like your partner is already able to work with a team.

You Wrote -
"Sometimes he hires subcontractor on freelancing sites to develop small modules"

CONCLUSION:
"Why do you see the speck in your brother's eye but fail to notice the beam in your own eye? "    - Mathew 7:3
C. Stark Send private email
Friday, March 01, 2013
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz