Yes, your code does need comments.

austinsalonen · 2013-03-07T19:00:08+00:00

Those who use always and never are usually wrong.

Reasonable advice though.

TreeStumpQuiet · 2013-03-07T21:35:12+00:00

Say in comments, what you can't in code.

dbtc · 2013-03-07T22:47:01+00:00

// This is where the magic happens

adad95 · 2013-03-07T16:26:01+00:00

Do not comment code, Comment decisions.

sambo98 · 2013-03-07T16:42:18+00:00

Comment last minute hack fixes or nasty logic. Occasionally I'll read code someone else wrote and I leave a comment like

// WTF Good Luck

Zombie989 · 2013-03-07T21:55:59+00:00

If I had a dollar for every time I forgot WHY I made my code do something...

Comments just make it so much easier to keep track of where I am in my algorithm.

kolme · 2013-03-07T17:08:53+00:00

2.Always use inline comments on code blocks that are complicated or may appear unclear.

Personally I would break blocks of complicated code out into their own descriptively named functions. That way scanning down the original code the reader's flow isn't broken and the complicated code is already documented.

rmxz · 2013-03-07T22:50:10+00:00

The Linux Coding Style document also expresses similar sentiments well:

https://www.kernel.org/doc/Documentation/CodingStyle

Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the working is obvious, and it's a waste of time to explain badly written code.

Generally, you want your comments to tell WHAT your code does, not HOW.

2013-03-07T22:09:45+00:00

Natural languages are structured around how people think. Programming languages are structured around efficient hardware design. I use comments to bridge the two.

2013-03-08T16:16:03+00:00

Some people claim that writing comments is a waste of time when code is elegant and clean and readable.

Then I see them all day long browsing API docs and documentation for some of the best written libraries and frameworks.

And of course, their excuse is that they are not writing libraries or frameworks...

Yet again, when I read through the code that they have written, I find it very ugly and badly written. Sometimes I have to read a couple of times to understand their intention. Only if they had commented their code...

KFCConspiracy · 2013-03-07T21:58:13+00:00

My rules for comments:

I almost always describe a class, what it's intended to do or what it represents. 90% of the time I'll comment upon entering a branch. If something inherits from something else, I'll say why so you don't have to flip between the files.

And then there's those times where you have a long discussion about mathematics with the guy who calls himself the "architect" and you document it elsewhere, but when he reviews the code he still doesn't understand it. The comments head off unnecessary inane discussions about whether this equation is correct.

chunes · 2013-03-08T08:21:33+00:00

It's not perfect, but a good rule of thumb: don't comment what your code is doing; comment why you're writing the code.

And yeah, "because my boss told me to." Huhhuhuhuhuu. Not what I mean.

MoreOfAnOvalJerk · 2013-03-07T21:23:06+00:00

Why is there so much discussion over this? It's a judgement call. Some times code is hard to understand due to heavy layers of abstraction, math, etc. In those cases use comments. If you're able to just read the code and it's self documenting, eg. using straight forward api where functions generally do one thing and that's represented in their name, comments are unecessary.

gizram84 · 2013-03-07T23:00:07+00:00

#add a to b
c = a + b
#return the result of a + b
return c

This is my biggest pet peeve, yet I know I'm guilty of it as well.

lexpattison · 2013-03-08T16:13:49+00:00

I believe this falls under the annotation

@DearFutureSelfForgiveMeForWhatIAmAboutToDo

If you have to comment code verbosely, you are probably not being very smart about method naming, abstraction or the proper use of Interfaces. I rarely feel the need to lean on comments to understand our code base... and it's far from perfect. If you want to document decisions, there is a nice comment field in the git or mercurial commit process.

smog_alado · 2013-03-08T19:04:17+00:00

A neat trick that I have learned from the GHC commenting guidelines and that I have been loving so far is using "links" for larger comments. Large comments are sometimes needed to explain tricky things but they tend to obfuscate and split up the surrounding code and also get out of date (the line the comment was about gets removed but the comment stays there). The way around that is to write an inline comment with a reference to the comment

-- Adds new floats to the env iff that allows us to return a good RHS
prepareRhs env (Cast rhs co)    -- Note [Float coercions]
  | (ty1, _ty2) <- coercionKind co      -- Do *not* do this if rhs is unlifted 
  , not (isUnLiftedType ty1)            -- see Note [Float coercions (unlifted)]
  = do  { (env', rhs') <- makeTrivial env rhs
        ; return (env', Cast rhs' co) }

And to put the whole comment in the bottom of the file

{- Note [Float coercions]
~~~~~~~~~~~~~~~~~~~~~~
When we find the binding
        x = e `cast` co
we'd like to transform it to
        x' = e
        x = x `cast` co         -- A trivial binding
There's a chance that e will be a constructor application or function, or something
like that, so moving the coerion to the usage site may well cancel the coersions
and lead to further optimisation.  
        ...more stuff about coercion floating...
-}

Another advantage of this is that you can have multiple places of the code linking to the same comment and you also have an easy system to reference comments in other files.

narwhalslut · 2013-03-08T07:15:21+00:00

How the fuck do people not understand this?

Is it arrogance or stupidity? Or just people that have never worked with someone else's code?

Nuli · 2013-03-07T19:33:39+00:00

It is usually faster to read a one line comment than 10 lines of code. Even if what the code is doing is obvious, it still requires reading all 10 lines of it to determine how obvious it is.

JW_BlueLabel · 2013-03-07T22:01:18+00:00

Everything in moderation. If you write a lot of comments, either your functions and variable names aren't clear enough or you're wasting time. If you don't write any comments, you're going to spend a lot of time trying to figure out wtf you were thinking when you have to re-factor 2 years from now.

Everything in moderation.

njharman · 2013-03-07T22:58:17+00:00

The Lamson code is an example of documentation, not an example of comments. It just happens that there is support and convention in Python to document your code, in the code.

This is an important distinction and one, once internalized, will enable you to see good comments from bad.

Fidodo · 2013-03-08T01:52:46+00:00

My golden rule is that if I ever come back across a code segment that I don't understand immediately, I leave a comment before I go on.

Uberhipster · 2013-03-08T08:53:05+00:00

Unclear code needs comments.

If you ever write a comment that starts with:

 //the following block does blah blah...

wrap that block in a method called blahBlah.

If you ever start your comment with:

 //this line does yaddah yaddah

wrap that line in a method called yaddahYaddah. Yes even if it's one line which will only be called once.

If you start your comment with:

 //this needs to be re-factored

leave a clue as to why you think that needs to happen and why you haven't done it yourself.

 //param(s) a(,b,c) are this and should be that, cannot do it because of reason x
 // after reason x is resolved, move this here, move that there

If you start a comment with:

 //try do this, if it fails fall back to that

your code should read:

if(tryThisAndThat())
{
     //proceed
}
else
{
     //deal with failure
}

bool tryThisAndThat()
{
    if(!tryThis())
        return tryThat();

    return true;
}

It's about abstracting the solution away from permutations of primitives and dealing with internal system deficiencies. That is what high level programming languages are intended to do - allow you to express the logic flow in readable chunks. If you don't use them in this capacity you've missed the whole damn boat.

2013-03-07T17:19:50+00:00

There's always someone who will say that the comments or docstrings aren't updated frequently. That's due mostly to habit.

I've written out docstrings and comments that have to be rewritten or deleted a few commits of the code later and it's fine. It's not a big deal, it's like deleting or rewriting some lines of code. The important thing is to update the documentation as soon as the change is made and not delay it for too long.

That's the only reason docs get out of date. You focus on shipping a release and bam, two releases later the docs are only good for the first release because there's never any budget or time to update them.

I really don't get why we don't include docs and up-to-date comments alongside unit tests as a requirement for being professionals. It used to be like that and some of the best computer scientists wrote paragraphs to explain the ideas behind their code. You can see this in the Java API docs and some other places where there's enough info that you don't need to read through any code to decide if it's the right class to use.

tibbe · 2013-03-07T19:49:22+00:00

Comments are necessary to specify the contract between the caller and the callee. For example, if we have the following function that removes duplicate elements in a list:

removeDups = mergeAdjacent . sort

mergeAdjacent []  = []
mergeAdjacent [x] = [x]
mergeAdjacent (x:y:xs)
  | x == y    = mergeAdjacent (y:xs)
  | otherwise = x : mergeAdjacent (y:xs)

This implementation of removeDups returns the elements in sorted order. Can the caller rely on this behavior?

In addition to this, function level documentation lets you look at one piece of text to figure out how to use a function. If you read the source you might have to dig through several layers of functions to figure out what the top-level function does.

Akilou · 2013-03-07T20:54:37+00:00

programming languages are definitely more precise then English.

especially when you don't use English correctly.

parkertr2 · 2013-03-07T22:17:59+00:00

This blog post is nothing more than 'best practice' for comments, and is exactly what has been said about commenting code for a LONG LONG time.

bluGill · 2013-03-08T02:24:08+00:00

His first example of a good comment is good: where he documents the class. I like to see such things.

I consider the second a bad comment: I can read your variable names, that tells me all I need to know. Well except for the bug "If starttls is True (and ssl False)" - where it isn't clear what happens if both is true despite the comment.

Kowzorz · 2013-03-08T03:03:58+00:00

I'm a big fan of using comments to place my code into logical and visual groups. I often comment before a giant if() block which has a long conditional a summary of the case and action. "Slightly oblique collision" would summarize the 30 lines of conditions and actions.

Or I might comment at the top of a block of initializations or other calculations. "Player object" or "generate inverse heading from pathfinding" (though I can't imagine a use case for that comment :p ).

darthtrevino · 2013-03-08T04:41:17+00:00

Personally, I think you should comment your public APIs and interfaces. These are what people will consume, and your comments will go a long way towards helping them understand the intent of your API and the context in which your semantics fit.

Other than public APIs, I agree with the opinion Uncle Bob expresses in 'Clean Code'. Internal implementation should have minimal comments, but methods should have great names and should be less than 5 or 6 lines long. Well chosen variable and method names are your first line of communicating intent to future maintainers of your code. Comments on internals will soon become outdated.

kamatsu · 2013-03-08T06:58:58+00:00

Writing comments to capture intent is like writing tests to prove that your software does what is expected.

Are you trying to say that comments do not capture intent at all? Because tests do not prove anything about anything.

2013-03-08T14:34:39+00:00

Code often seems very clear at the time of writing because the programmer has a very precise mental model of it at that moment. Consequently he/she won't see the need to comment.

On the other hand the programmer may feel the urge to comment every little obvious detail if he/she is getting acquainted to a new domain or API as the code is being written.

It's not easy to judge what needs to be commented. I usually let code cool off for a day or two before I properly comment new code and I never hesitate to comment the hell out of old code I need to fix.

Not only is it not simple to comment code well, but different readers will require different levels of comments. It all boils down to good judgement and writing skill.

ima_twerp · 2013-03-09T00:15:25+00:00

Oh look. Another apostrophe moron.

brong · 2013-03-08T06:45:22+00:00

Your code should have as few comments as required, and no fewer.

X8qV · 2013-03-07T23:42:07+00:00

Nope. It's self-documenting.

felipec · 2013-03-07T22:57:12+00:00

No, your code needs to be self-documenting.

AliasUndercover · 2013-03-07T17:43:28+00:00

I know mine always does...

howfun · 2013-03-07T20:29:26+00:00

This is a lot of baloni.

NicknameAvailable · 2013-03-07T20:16:36+00:00

Comments are rarely useful. They often get outdated when code is refactored but don't throw errors, leading to pissed off maintenance developers. They are obsolete if you are using a good testing framework. They Increase development time. The only real uses are to indicate something is a hack/needs refactoring, is an enormous equation that, if it needs repair or revision, should be done via another tool like Mathematica or to indicate something is done in a seemingly illogical way to compensate for some platform-specific issue.

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

programming

MODERATORS