| Author |
Message |
Antimon
Joined: Jan 18, 2005
Posts: 4145
Location: Sweden
Audio files: 371
G2 patch files: 100
|
 Posted: Tue May 04, 2010 4:09 am Post subject:
Code comments
Subject description: How I do it |
  |
|
I've was criticized a while ago for writing uncommented code, and I thought I'd explain why (since it's a conscious thing - I don't write comments because I don't want to). This is not me telling you that I do it the right way and you should do likewise, but perhaps it might give a different angle on how to program and spark a fun discussion.
First off, comments introduce redundancy in the code. Redundancy in a computer program is generally a bad thing, and with comments (the original intentionbeing to aid the programmer) it can serve to confuse and hinder the programmer's work. Here's an example:
Programmer A has written a piece of code containing this somewhere in the middle:
| Code: | // Subtract one from the zflorq
1 -=> container[ZFLORQ_INDEX]; |
Time passes. Programmer B discovers that (due to changes elsewhere in the code), you actually need to add one to the zflorq in this place. Unfortunately, B has developed a blind spot for comments and thus only fixes the code:
| Code: | // Subtract one from the zflorq
1 +=> container[ZFLORQ_INDEX]; |
More time passes. Programmer C needs to do an extensive refactoring in the program, including the aforementioned piece of code. As he encounters a line that does one thing and an attached comment saying that the line should actually do something else, he is confused. He tries to ask A and B, but they are both working on other stuff and have forgotten what this piece of code does.
There are two possiblilities here, either the code is wrong, or the comment is wrong. Odds are in favour of the code since the program seems to run ok, but if it's a complicated program it might just as well be that the program is wrong and this particular bug hasn't caused a visible error yet.
This example can work if A, B and C are the same person and sufficiently long amounts of time pass between the three phases. This issue can cause great damage if C is shown the piece of code as part of a tutorial, as in B being a teacher and C his student.
The solution is to write easy to read code instead of comments. In my view the code above does not need any comment - it can be understood as it is. More complicated code may benefit from being moved to dedicated functions with long and explanatory names, or assigned to temporary variables with long and explanatory names (the time it takes to program is more affected about thinking speed than typing speed).
| Code: | fun void incrementZflorqAndSendToGlulx(int[] @ container, int hlarfCount) {
1 +=> container[ZFLORQ_INDEX];
Sender.send(container[ZFLORQ_INDEX], hlarfCount);
} |
the idea with the funny names in this post is that each funny name identifies a well-known entity in the context of the program, so that the programmer will instantly know what a hlarf, glulx or zflorq is. If the entity isn't well-known, the name should be replaced by something that is well-known, even if it's more to type.
Exceptions to the rule about long variable names are standard names that are connected to common constructs, like 'i' in a for loop.
As I said, this is just my take on things, based on working in a team environment where the general programming competence of team members is very varied indeed. If you've never ever caused discrepancy between comments and the code they explain, then by all means continue as you have.
Another argument for me is that comments clutter up the code and actually make it harder to read (especially if every second or third line is a comment, which happens now and then), but I suspect that may just be me.
I should stress that the point I am making is that you should make easier-to-read code rather than delete comments from all your programs. And sometimes, if a piece of code does something unexpected in context, or just is kind of complicated, a comment explaining what it does and why may be called for.
Thoughts? Am I totally insane? ;)
/Stefan
_________________
Antimon's Window
@soundcloud @Flattr home - you can't explain music |
|
|
Back to top
|
|
 |
DrJustice
Joined: Sep 13, 2004
Posts: 2112
Location: Morokulien
Audio files: 4
|
| Posted: Tue May 04, 2010 5:28 am Post subject:
|
|
|
| Antimon wrote: | Am I totally insane? 
|
Completely!
Nah... 
In your example it does indeed seem redundant. There's certainly no need to comment every (obvious) statement.
Personally, I like helpful comments. It has saved my hide a number of times when revisiting old code, and my colleagues appreciate it. Sometimes I've missed it in code that I've been given to work with.
I usually give most non-trivial functions an explanatory comment; basically what the purpose of it is, any special considerations and what the entry and exit conditions are. Sometimes I will comment a statement or a group of statements that could do well a short explanation. Of course comments should be maintained, just like code, so that the situation you described would not arise.
But as you say, writing easy to read code is the most important thing. I format my code specifically to make it as evident as possible what the logic and the structure is. BTW, this rules out old testament style (K&R), and sometimes VeryLongAndComplicatedNamesAreNotTheSolution.
That's my 2 øre.
DJ
-- |
|
|
Back to top
|
|
|
Kassen
Janitor
Joined: Jul 06, 2004
Posts: 7678
Location: The Hague, NL
G2 patch files: 3
|
Posted: Sun May 09, 2010 12:25 am Post subject:
Re: Code comments
Subject description: How I do it |
|
|
| Antimon wrote: |
First off, comments introduce redundancy in the code. Redundancy in a computer program is generally a bad thing, and with comments (the original intentionbeing to aid the programmer) it can serve to confuse and hinder the programmer's work. Here's an example:
|
Isn't this a bit like saying guard-dogs are better than safes because if I get a safe, then run out of space in it, resolve to replace it with a bigger one, starting by throwing out the small safe yet forgetting to get a bigger one my valuables will be out in the open. That wouldn't happen with a dog.
:-p
Some people advocate writing (and editing) the comments first, before the code.
I agree that you can over-comment and that might mean clutter, but some structures simply are hard to understand. A complicated function, without comments might be as bad as a magic number; it might not be clear where it came from or what it's trying to do at all. Some structures might have a non-obvious form due to optimisation, in which case commenting out the non-optimised form might help explain what's up. Some parts of a program might work around a bug in the language, in which case a comment will help explain what's going on, indicating that that part shouldn't be edited until this bug is fixed.
While comments may clutter it can also help a lot to clearly label major sections of the program
///////////////////////////
///// LIKE THIS ///////
//////////////////////////
to help looking for parts when scrolling quickly.
Generally I think that the bigger the project the more important it becomes to comment clearly. When using some sort of unusual larger design the design itself will likely need a description too.
_________________
Kassen |
|
|
Back to top
|
|
|
Antimon
Joined: Jan 18, 2005
Posts: 4145
Location: Sweden
Audio files: 371
G2 patch files: 100
|
Posted: Sun May 09, 2010 6:35 am Post subject:
Re: Code comments
Subject description: How I do it |
|
|
| Kassen wrote: | | Antimon wrote: |
First off, comments introduce redundancy in the code. Redundancy in a computer program is generally a bad thing, and with comments (the original intentionbeing to aid the programmer) it can serve to confuse and hinder the programmer's work. Here's an example:
|
Isn't this a bit like saying guard-dogs are better than safes because if I get a safe, then run out of space in it, resolve to replace it with a bigger one, starting by throwing out the small safe yet forgetting to get a bigger one my valuables will be out in the open. That wouldn't happen with a dog. |
My head is heavy today - I don't get this analogy. OTOH, I can't really think of a good analogy either, except that a comment is a bit like source code, only in spoken-language form, and instead of talking to a compiler it is telling a human about stuff. It's a bit like having the same code in two different methods a and b, and sometimes you use a and sometimes b. Anytime you have this there is a risk that something will be changed in a but not in b because you forgot about it. After that the program might start to subtly work poorly.
EDIT: and I want to stress that a program that subtly works poorly generally is much more difficult to fix than a program that crashes hard - the bugs may be detected a longer time after they were introduced.
| Quote: | | A complicated function, without comments might be as bad as a magic number; it might not be clear where it came from or what it's trying to do at all. |
True - but what I'm advocating is that you should stop here and take a moment to think about why you have written a function that is as complicated as a magic number. Could it be split up, the names become more explanatory etc, whithout lessening the quality of the code? Sometimes code is hard to read because it could be written better.
Heavily optimised stuff with remote and/or indirect dependencies can certainly deserve comments. Comments are also a good way to mark sections in ChucK code. I'm just saying, don't overdo it.
/Stefan
_________________
Antimon's Window
@soundcloud @Flattr home - you can't explain music |
|
|
Back to top
|
|
|
Kassen
Janitor
Joined: Jul 06, 2004
Posts: 7678
Location: The Hague, NL
G2 patch files: 3
|
| Posted: Sun May 09, 2010 8:42 am Post subject:
|
|
|
It was a bad analogy. What I meant was that you can't compare two methods and assume one will be carried out in the wrong way.
_________________
Kassen |
|
|
Back to top
|
|
|
|
Forum index » DIY Hardware and Software » ChucK programming language
FAQ
Calendar
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
Chat Room
