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
I used to comment my procedures after the procedure name, like:
Function DoIt(thingie as string) as Boolean '*======== '* Purpose: Do it '* Mod1 : and do it now '* Accepts: Thingie (What you're going to do it to) '* Returns: True if did it, else False '* Author : Ian Dennis based on code provided by Steve Smith '* Date : 01/02/2009 '* Mod1 : 02/10/2009... but I've noticed that both VB.Net and C# make use of XML comments, which happen before the procedure name, like:''' <summary> ''' Do It and do it now ''' </summary> ''' <param name="thingie">What you're going to do it to</param> ''' <returns>True if done, else False</returns> Function DoIt(thingie as string) as BooleanAs the XML helps with intellisense, I've started switching to that format -
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 remembered Borland well and used nested comments. VC++ doesn't currently support them (to my knowledge.)
PIEBALDconsult wrote:
And anyway, how would the other style help with that?
Because they can be nested by a /* */ when you want to temporarily block out some code (and with code highlighting, it becomes really obvious what you did.
-
But if you had malformed comments that included the open or the close trigger as regular text, that could get ugly fast.
Narf.
Never had that.
-
Never had that.
-
I was speaking past tense. Henceforth, I will never use comments and therefore never see this. :)
-
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 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.
-
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
Don't comment that line.... :laugh: Rename the function to InitArrayOfPoints() instead
-
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 can see why things like this may be done - the programemr first writes code, then comments it. This may (theoretically) benefit the original programmer in that the code is fresh in his memory, and writing a comment to reflect what it does may "force" him to spot subtle errors. (Of course, same can be said about the traditional "above"-style commenting, but I think the "below"-style makes sense here). I think the "below" style would also benefit a new programmer trying to understand or debug the code - she reads the code, understands (hopefully) it, and then reads the intention - if they dont match, well, there's clearly a problem with the code. How's that for a possible "why?" ?
"Impossible" is just an opinion.
-
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
At university I was always told that comments should go before the code rather than after. It's the way our brains work, top to bottom, left to right. Comments below the line is just weird, and looks weird. The comment looks far too wordy though. Surely 'initializes points' is enough. If it was me I would do
InitPoints();or maybe justInit();if it was a small application. The function name is enough to guess what it does. -
Generally, comments have always been written above or on the same line as the code. My objection to having comments below the relevant code is that it would be awkward if it was consistant:
Init();
// Init blah de blahis fine, but
private MyClass[] GetMyClassInstances(int count, bool why, string whathaveyou...)
{
... body of long function
}
/// GetMyClass does whatever it does
/// Parameters: whatever they areis just asking for trouble!
No trees were harmed in the sending of this message; however, a significant number of electrons were slightly inconvenienced. This message is made of fully recyclable Zeros and Ones "Rumour has it that if you play Microsoft CDs backwards you will hear Satanic messages.Worse still, is that if you play them forwards they will install Windows"
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
-
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 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:
