Commentaries - above or below the code?
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
Above...unless you really don't like the person who will be maintaining the code.
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
I have a habit of putting comments to the right of the code.
Init(); // Here we do some thing with other things that do stuff to things
Probably a habit leftover from my assembler days. Which would be just yesterday, in fact.
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
As someone who has only taken a few programming classes, and learned everything else on my own my opinion may be a bit skewed. :omg: I prefer the comments above the code for two reasons. First I have learned a lot from studying other peoples code and having the comments above the code helps me follow along and figure out what they are doing and then how they are doing it. Second in my own code it helps me to go back later and kind of follow the logic of what I am trying to do so I can go back later to see if I missed something. Kinda of a "Do this, like this, then do that, like this . . ." This probably isn't as important for most of you but as someone who doesn't code for a living, but has to code to make their living it can be such a big help. ;) T
-
What are these green things in your code ;-) Code should be written in such a way that it is self documenting!
As much as possible, yes. The mistake is when you believe no commenting is necessary because your code is so wonderfully written. Can't tell if you really take it that far, of course.
-
As much as possible, yes. The mistake is when you believe no commenting is necessary because your code is so wonderfully written. Can't tell if you really take it that far, of course.
To be honest when i write code it falls into 2 distinct camps: The stuff I understand and the stuff I don't. There's no point commenting the former and I wouldn't know where to start with the latter ;-)
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
Having both taught computer programming and done it for a living, I find that comments serve two distinct purposes. In the classroom, a comment explains "here is what this code does"; because, when teaching, you introduce an idea and then you explain it. It is appropriate to put such comments immediately following the line of code, but only for didactic purposes. In the production world, a comment explains "here is what this code is for"; and should go above the code (or, if very brief, next to it).
-
Hahahaha... Totally agree!!! Comments above or on the same line (if it's a very simple comment)... Edit: And what about useless comments???... Have you ever wrote those???... Like: // Check if a > b if (a > b) { (...) } Hahahaha... It seems too stupid, but I must confess I've done it a couple of times...
modified on Thursday, November 12, 2009 6:49 AM
-
What are these green things in your code ;-) Code should be written in such a way that it is self documenting!
:laugh: Nowadays I write big visualization apps for plants and machines - the code would be a miracle without comments - not because of messy code - but you wouldn't understand why it was done this way (the code doesn't explain the machine - you see?). When I was a junior developer I thought like you (of course we are all proud of our perfect coding style) - but when I worked on my first big C++ project (~ 1 Million lines of code - without any comment!) I realized how stupid this ideology was... (It wasn't all my code, and comments where forbidden by the style-guide for faster builds (the whole app had about 35 Million lines)) Now I'm a big fan of comments - sometimes I write them before i write any code, to get a clear structure of the problem - if you can describe a problem in normal words it's easy to write the code. So everyone can understand my code (even my boss or my wife ;P ). If you ever have to take over a well documented piece of code from someone else, you will see how nice it is just to skim over the comments to see WHAT the code does - later you can read the "self documenting" code to see HOW it was done. btw: Comments before the code! :rose:
-
:laugh: Nowadays I write big visualization apps for plants and machines - the code would be a miracle without comments - not because of messy code - but you wouldn't understand why it was done this way (the code doesn't explain the machine - you see?). When I was a junior developer I thought like you (of course we are all proud of our perfect coding style) - but when I worked on my first big C++ project (~ 1 Million lines of code - without any comment!) I realized how stupid this ideology was... (It wasn't all my code, and comments where forbidden by the style-guide for faster builds (the whole app had about 35 Million lines)) Now I'm a big fan of comments - sometimes I write them before i write any code, to get a clear structure of the problem - if you can describe a problem in normal words it's easy to write the code. So everyone can understand my code (even my boss or my wife ;P ). If you ever have to take over a well documented piece of code from someone else, you will see how nice it is just to skim over the comments to see WHAT the code does - later you can read the "self documenting" code to see HOW it was done. btw: Comments before the code! :rose:
just in case there's any confusion I do put comments in my code when it matters. Excessive comments, especially where 90% of them are meaningless just cause people to ignore them and you might as well not have added any. I'd rather write a big chunk when I get to a point that really needs explaining and leave the shorter (trivial) methods without any comments at all.
-
:laugh: Nowadays I write big visualization apps for plants and machines - the code would be a miracle without comments - not because of messy code - but you wouldn't understand why it was done this way (the code doesn't explain the machine - you see?). When I was a junior developer I thought like you (of course we are all proud of our perfect coding style) - but when I worked on my first big C++ project (~ 1 Million lines of code - without any comment!) I realized how stupid this ideology was... (It wasn't all my code, and comments where forbidden by the style-guide for faster builds (the whole app had about 35 Million lines)) Now I'm a big fan of comments - sometimes I write them before i write any code, to get a clear structure of the problem - if you can describe a problem in normal words it's easy to write the code. So everyone can understand my code (even my boss or my wife ;P ). If you ever have to take over a well documented piece of code from someone else, you will see how nice it is just to skim over the comments to see WHAT the code does - later you can read the "self documenting" code to see HOW it was done. btw: Comments before the code! :rose:
johannesnestler wrote:
When I was a junior developer I thought like you (of course we are all proud of our perfect coding style) - but when I worked on my first big C++ project (~ 1 Million lines of code - without any comment!) I realized how stupid this ideology was... (It wasn't all my code, and comments where forbidden by the style-guide for faster builds (the whole app had about 35 Million lines))
Did having a few percent of the lines be comments actually have a meaningful impact on the build time; or like most style guide content, was it the product of someone who took a role writing in word because he couldn't hack it as a coder?
3x12=36 2x12=24 1x12=12 0x12=18
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
-
Yes, it does matter. They should be positioned in the recycle bin.
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
I always defer to my favorite software book Code Complete for these kinds of questions. McConnell spends a whole chapter talking about best practices in writing comments. (This may seem silly to some, but if you read the book, it makes a TON of sense.) Chapter 32 states plainly "Use comments to prepare the reader for what is to follow", and explains the well-established convention of putting comments above the code it's documenting. Further (and this is the fun part you can show your professor), he claims "This idea isn't always taught in programming classes, but it's a well-established convention in commercial practice." Well-established conventions, until there is a clear technical reason to do otherwise, should be followed! Also, there has been some discussion hinting that well-crafted code should not need comments. My thought is all about how fast you can look at code to quickly understand what it's supposed to do. Your brain doesn't waste time translating variable names (even if they're well named), doing math, finding control loop conditions, etc. Stuart
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
A couple of lines for general explanation above the code block, and short 2 or 3 word comments at the end of appropriate lines to explain what a particular variable or called function is for. Always worked for me.
-
A programmingcommenting question. I have been writing commentaries above a related line of code, like this:
// The Init() method we call here initializes an array of points
Init();However, I have seen a big sample of code written by one of my professors recently. The commentaries was placed below a line.
Init();
// The Init() method we call here initializes an array of pointsSincerely, I have found it very clear and understable. Did anybody encounter such approach to commenting code? Is it recommended?
Greetings - Jacek
Personally, my comments generally come before the code, but it's because of the way I code. I don't set out to write comments; rather, as I enter a new conceptual block, I find that it helps clear my mind to write a quick explanation of what I'm going to do. Then I find it easier to focus on what needs to be done within the conceptual block. Thus, the comments I write actually direct the code, rather than the other way around. I don't need to go back over the code and add comments this way. Basically, if there's a comment in the code, it's because it was needed to write the code; if there's not, it's because the conceptual block was straight-forward enough that this guide wasn't necessary for my initial thoughts. I suppose you could say my coding style is self-commenting. Or is my commenting style self-coding? :)
-
Or even better, rename the function so you don't need the comment.
That's right. The old 'self documenting code' joke is not always a joke. Take time and space to make variable names mean something. Make the method name be really indicative of what it does. I use long, descriptive variable and method names, and my experience is that they are more likely to stay up to date than the comments are, and less likely to be re-used in an inappropriate manner. 'int i;' will get used/reused on demand, but 'int windowIdx; will generally only be used for the index of a window, into a list of windows. But comments are required where the code can not be made easy to understand, because it is actually very complex algorithm, it has been optimized, or for some other reason obfuscated.
Silver member by constant and unflinching longevity.
-
Comments below the line of code? Sure, if you're the sort of person who wears their underpants on top of their trousers.
"People who don't like their beliefs being laughed at shouldn't have such funny beliefs." ~ Anon "If you can't explain it simply, you don't understand it well enough" ~ Albert Einstein Currently reading: 'The Greatest Show on Earth', by Richard Dawkins.
-
"You botched it", basically, for different values of "it".
Personally, I love the idea that Raymond spends his nights posting bad regexs to mailing lists under the pseudonym of Jane Smith. He'd be like a super hero, only more nerdy and less useful. [Trevel]
| FoldWithUs! | sighist | µLaunch - program launcher for server core and hyper-v server -
As almost everyone has replied previously, generally comments appear above the code or inline. In the world of academia, where real-world applications, programming teams and programmers are sparse to non-existent, you may find lots of things that are different to what really goes out in the real-world. That being said, although I may be wrong, there is one time when I will put a comment after the line of code, and that is in the case of 'else'.
// This explains what will happen when 'condition' is true
if( true )
{
...
}
else
{
// This explains what happens in other cases
}I'm not sure what others do in this case, but then again, it is very specific, only appears inside a function block, and is pretty clear when reading the code.