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
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. :)
-
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.