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
-
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 for intention, behind for details. In-Method comments should show the intention of the block they are commenting on (instead of repeating what the code says). A reader of the code should be able to skim over the coments to understand the structure of the code. In virtually all cultures title and abstract go before the actual content. Code should be no different.
// Find appropriate file
path = GetDefaultPath();
if (!path.Exists()) // alternate path (clients < 1.7)
path = GetDefaultPathV1();// check for pending transactions
...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 -
If it's a small comment, you could even do this:
Init(); // The Init() method we call here initializes an array of points
Regards, Nish
Nish’s thoughts on MFC, C++/CLI and .NET (my blog)
My latest book : C++/CLI in Action / Amazon.com linkSome people can't see with wood from the trees :)
Software Kinetics (requires SL3 beta) - Moving software
-
If it's a small comment, you could even do this:
Init(); // The Init() method we call here initializes an array of points
Regards, Nish
Nish’s thoughts on MFC, C++/CLI and .NET (my blog)
My latest book : C++/CLI in Action / Amazon.com linkOr even better, rename the function so you don't need the comment.
-
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
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"
-
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 agree with the consensus, above. It is easier to read, and tells you what to expect.
------------------------------------ In science, 'fact' can only mean 'confirmed to such a degree that it would be perverse to withhold provisional assent.' I suppose that apples might start to rise tomorrow, but the possibility does not merit equal time in physics classrooms. Stephen J Gould
-
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
What are these green things in your code ;-) Code should be written in such a way that it is self documenting!
-
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 or beside. /* And never with those lazy C++-style comments; only use proper C-style comments. */
-
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
You may like the Literate Programming[^] approach where the actual code is just a small piece of text embedded into comments.
-
Above or beside. /* And never with those lazy C++-style comments; only use proper C-style comments. */
-
Ah, I sit corrected. But B seems to be where it changed. I guess I'll call them B-style comments from now on. Edit: Hmmm... corrected again, the B document says, "Comments are delimited as in PL/I by /* and */." So I guess they're PL/I-style comments.
modified on Wednesday, November 11, 2009 11:36 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
Comments are for sissies. ;) Marc
I'm not overthinking the problem, I just felt like I needed a small, unimportant, uninteresting rant! - Martin Hart Turner
-
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
In Plain English there is no need for comments. The longer term residents of the lounge will get this one, while newer members should Google for osmosian.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith
As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
-
In Plain English there is no need for comments. The longer term residents of the lounge will get this one, while newer members should Google for osmosian.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith
As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
There is, however, a need for plain english in comments...especially if the comments are in Plain English.
-
In Plain English there is no need for comments. The longer term residents of the lounge will get this one, while newer members should Google for osmosian.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith
As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
Pete O'Hanlon wrote:
In Plain English there is no need for comments.
My gf claims to speak to me in Plain English, but I still can't figure out what she's saying. ;) Marc
I'm not overthinking the problem, I just felt like I needed a small, unimportant, uninteresting rant! - Martin Hart Turner
-
Above or beside. /* And never with those lazy C++-style comments; only use proper C-style comments. */
Except you can't enclose a block of code with C (/* */) style comments with a C style comment. One of the dumbest things ever.
-
Pete O'Hanlon wrote:
In Plain English there is no need for comments.
My gf claims to speak to me in Plain English, but I still can't figure out what she's saying. ;) Marc
I'm not overthinking the problem, I just felt like I needed a small, unimportant, uninteresting rant! - Martin Hart Turner
"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 -
Except you can't enclose a block of code with C (/* */) style comments with a C style comment. One of the dumbest things ever.
That depends on the compiler; you can select it on some:
Borland C++ 5.5 for Win32 Copyright (c) 1993, 2000 Borland
Syntax is: BCC32 [ options ] file[s] * = default; -x- = turn switch x off
-3 * 80386 Instructions -4 80486 Instructions
-5 Pentium Instructions -6 Pentium Pro Instructions
-Ax Disable extensions -B Compile via assembly
-C Allow nested comments -Dxxx Define macroAnd anyway, how would the other style help with that?
-
That depends on the compiler; you can select it on some:
Borland C++ 5.5 for Win32 Copyright (c) 1993, 2000 Borland
Syntax is: BCC32 [ options ] file[s] * = default; -x- = turn switch x off
-3 * 80386 Instructions -4 80486 Instructions
-5 Pentium Instructions -6 Pentium Pro Instructions
-Ax Disable extensions -B Compile via assembly
-C Allow nested comments -Dxxx Define macroAnd anyway, how would the other style help with that?
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.
-
Pete O'Hanlon wrote:
In Plain English there is no need for comments.
My gf claims to speak to me in Plain English, but I still can't figure out what she's saying. ;) Marc
I'm not overthinking the problem, I just felt like I needed a small, unimportant, uninteresting rant! - Martin Hart Turner
She's speaking Plain English, and we're listening in Penis.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith
As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
