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 Humans read downwards and we want to know what you intend to do (comment) before we read what you are doing (code).
'--8<------------------------ Ex Datis: Duncan Jones Merrion Computing Ltd
-
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 on the same line, but never below.
“Follow your bliss.” – Joseph Campbell
-
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 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.
-
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. When reading code it helps you to understand what the following line does.
If you fail to plan, you plan to fail! Books are as useful to a stupid person as a mirror is useful to a blind person. - Chanakya
-
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.
-
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
