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
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.
-
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.
Pete O'Hanlon wrote:
She's speaking Plain English, and we're listening in Penis.
:laugh: :-O 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
Everyone, for ever, has placed it above. Let's just stick to the accepted pattern and move along.
cheers, Chris Maunder The Code Project Co-founder Microsoft C++ MVP
-
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. :)