Comment your damn code

#1

Post by yShrike » Mon, Nov 12, 2012, 1:07 PM UTC

Comment your damn code
tech.collectedit.com

Re: Comment your damn code

#2

Post by lmm » Mon, Nov 12, 2012, 1:23 PM UTC

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

Re: Comment your damn code

#3

Post by hnwh » Mon, Nov 12, 2012, 1:49 PM UTC

lmm wrote: post #2

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

I'd really like this to be reality.. but in my world, there are too many programmers who don't write code "the right way". like > %80. For the great programmers sure ok, its obvious, but for the rest of them.. no.. you're not the coding genius you think you are.. please comment your code. Don't be tricky, clever, smart.. or self-documenting. Comment. period.

Re: Comment your damn code

#4

Post by peteretep » Mon, Nov 12, 2012, 1:50 PM UTC

lmm wrote: post #2

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

> A well-written method doesn't need explanation, because it obviously couldn't have been written any other way

I don't think I have anything nice I can say here, other than this smacks of the hopeless naivety

Re: Comment your damn code

#5

Post by yummyfajitas » Mon, Nov 12, 2012, 1:52 PM UTC

hnwh wrote: post #3

lmm wrote: post #2

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

I'd really like this to be reality.. but in my world, there are too many programmers who don't write code "the right way". like > %80. For the great programmers sure ok, its obvious, but for the rest of them.. no.. you're not the coding genius you think you are.. please comment your code. Don't be tricky, clever, smart.. or self-documenting. Comment. period.

If a programmer is incapable of doing this:

    maybeGetFileHandle :: FilePath -> IOLikeMonad (Maybe Handle)

Why do you think they are capable of doing this?

    foo :: FilePath -> IOLikeMonad (Maybe Handle)
    -- If the file is available and can be read
    -- return Some handle. Otherwise, return None.

Re: Comment your damn code

#6

Post by vetler » Mon, Nov 12, 2012, 1:52 PM UTC

lmm wrote: post #2

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

One problem with this, is that it's probably subjective what nonobvious code actually is. Of course, it's subjective how much commenting is enough, as well. In my experience, projects where it has been decided that comments are not required, have ended up with uncommented and nonobvious code - the worst of both worlds.

This could perhaps been prevented given proper code review processes, that were not in place. However, in a project with varied skill level, I would personally prefer advocating both commenting and obvious code, since the end result will probably be something inbetween.

Re: Comment your damn code

#7

Post by Toshio » Mon, Nov 12, 2012, 1:54 PM UTC

Well, I disagree.

Test-drive your damn code. The difference in positive impact will be a few orders of magnitude.

Re: Comment your damn code

#8

Post by bitdiffusion » Mon, Nov 12, 2012, 1:59 PM UTC

"Look, there is what you intend and what you write. Your bugs are in between the two."

Umm no. Bugs are usually

a) a misinterpreation of the requirements (no amount of comments are going to save you) or

b) a (hopefully) subtle error in the code - again - I don't see how a comment is going to help you unless the comment is practically pseudo-code which I (hope) nobody is advocating.

Anyone have an example of the typical type of bug that is easier to fix when there are comments around? I agree about commenting "non-obvious" code though - at least in terms of it's intentions. Not necessarily as a way to fix bugs, but to prevent the next programmer from removing something that looks superfluous because nobody can remember why it's there. Something like (totally made up):

"Assign the customer id as a prefix to the comment field; SAP expects the format of __ during import".

Re: Comment your damn code

#9

Post by xutopia » Mon, Nov 12, 2012, 2:01 PM UTC

Test it first and you'll notice that comments become near useless.

Re: Comment your damn code

#10

Post by rvkennedy » Mon, Nov 12, 2012, 2:07 PM UTC

Why comments are important: they represent intention.

A reasonable complex method can have a wide variety of inputs which the author can't be expected to have tested across the entire range of values. For example, if you have six boolean inputs, you have 2^6=64 possible combinations.

If you have six integer inputs, you have roughly (4e9)^6=4e57 combinations, which is more than the number of atoms in the Earth.

Expressing your intention means that when you (or someone else) come back to the code to change it, you can at least have an awareness of whether the behaviour you are seeing is in line with what you intended. Because a bug might not even be a bug - in that code - but a misuse of a method for something it wasn't meant to do.