Whether to use punctuation in comments or not?
-
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
I don't think there is a standard. What I do is that I put a period after long comments (full sentences), while short comments don't end with a period:
// Open the file, process it and if something bad happens, throw an // exception that will be caught by the calling code. // Just close the fileIt works for me :)Luis Alonso Ramos Intelectix Chihuahua, Mexico
-
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
//
// In general, I make block comments that are 'narrative' use full
// sentences and/or paragraphs. That means they get full punctuation,
// including the terminating period.
//// one line descriptive comments aren't sentences
Software Zen:
delete this; -
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
-
Yes. Also, spelling counts.
----
I don't care what you consider witty, but at least I do not blather on posting nonsense like Jim Crafton.
-- Stringcheese, humbled by Crafton's ability to string together multiple sentences
And if you can work some ASCII art in, all the better.
/* /\
//\\
//\\
//\\
||
|| */regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
-
And if you can work some ASCII art in, all the better.
/* /\
//\\
//\\
//\\
||
|| */regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
Absolutely! :) Actually, there's a tool around here somewhere for doing ASCII flowcharts in comments; i've used that before for sketching out class hierarchies at the top of source files.
You must be careful in the forest Broken glass and rusty nails If you're to bring back something for us I have bullets for sale...
-
Absolutely! :) Actually, there's a tool around here somewhere for doing ASCII flowcharts in comments; i've used that before for sketching out class hierarchies at the top of source files.
You must be careful in the forest Broken glass and rusty nails If you're to bring back something for us I have bullets for sale...
Ah! So that is what that comment was in my colleague's code. I thought he was trying to draw a frame from The Simpsons.
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
-
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
Where my comments are plain English, I use standard English punctuation. Where the comments are technical metadat, I don't. E.g. of case #2 using (SomeObject) { }// using SomeObject
-
Ah! So that is what that comment was in my colleague's code. I thought he was trying to draw a frame from The Simpsons.
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
Heh. I've also used ASCII logos, and that ASCII-art version of the cover from Fear and Loathing in Las Vegas... Whatever best describes the code, ya know? ;)
----
I don't care what you consider witty, but at least I do not blather on posting nonsense like Jim Crafton.
-- Stringcheese, humbled by Crafton's ability to string together multiple sentences
-
// Yes.
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
// No But then you knew I was going to say that, eh? ;P
// Seriously though, I don't put periods at the end of my comments, but I will
// .. for a sentence break in the middle of one. Why? I really have no idea,
// .. it has always been that wayThen again, I am one of those weird people who still uses two spaces after a period for readability.
Ðavid Wulff What kind of music should programmers listen to?
Join the Code Project Last.fm group | dwulff
I'm so gangsta I eat cereal without the milk -
And if you can work some ASCII art in, all the better.
/* /\
//\\
//\\
//\\
||
|| */regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
Cool! I actually *do* have ascii art in all my projects source code comments at some point or another. I figure it will amuse someone some day down the road since no one else ever looks at the great majority of my code anyway. It serves a useful purpose in denoting blocks of commonly related code such as separating the Microsoft auto generated form code in c# winform projects from my own code:
// __ _ _ ___ ____ __ __ __ __ __ ___ ___
// / _)( )( )/ __)(_ _)/ \( \/ ) / _)/ \( \( _)
//( (_ )()( \__ \ )( ( () )) ( ( (_( () )) ) )) _)
// \__) \__/ (___/ (__) \__/(_/\/\_) \__)\__/(___/(___)
"I don't want more choice. I just want better things!" - Edina Monsoon
-
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
If you program in, say, C# do you sometimes put a semi-colon at the end of a statement and sometimes not? No, because the compiler rejects the code as being incorrect. In my opinion, the same standard for quality and accuracy should be applied to comments as well. Why write beautiful code and then decorate it with ignorant boogers?
:josh: My WPF Blog[^] The greatest danger for most of us is not that our aim is too high and we miss it, but that it is too low and we reach it. - Michelangelo (1475-1564)
-
// No But then you knew I was going to say that, eh? ;P
// Seriously though, I don't put periods at the end of my comments, but I will
// .. for a sentence break in the middle of one. Why? I really have no idea,
// .. it has always been that wayThen again, I am one of those weird people who still uses two spaces after a period for readability.
Ðavid Wulff What kind of music should programmers listen to?
Join the Code Project Last.fm group | dwulff
I'm so gangsta I eat cereal without the milkGood idea actually though I tend to just indent paragraphs. So far I've written half my life story into my code...
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
-
Good idea actually though I tend to just indent paragraphs. So far I've written half my life story into my code...
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
Paul Watson wrote:
So far I've written half my life story into my code...
awesome
----------------------------------------------------------- Completion Deadline: two days before the day after tomorrow
-
I would be thankful if someone tell me the answer. What is the standard usage? In the easiest, I mean I would like to know whether to put . at the end of my comment or not:)
If it's a sentence, write it like a sentence. If it's fragment, don't end it with a period. Marc
-
Good idea actually though I tend to just indent paragraphs. So far I've written half my life story into my code...
regards, Paul Watson Ireland & South Africa
Shog9 wrote:
And with that, Paul closed his browser, sipped his herbal tea, fixed the flower in his hair, and smiled brightly at the multitude of cute, furry animals flocking around the grassy hillside where he sat coding Ruby on his Mac...
-
If you program in, say, C# do you sometimes put a semi-colon at the end of a statement and sometimes not? No, because the compiler rejects the code as being incorrect. In my opinion, the same standard for quality and accuracy should be applied to comments as well. Why write beautiful code and then decorate it with ignorant boogers?
:josh: My WPF Blog[^] The greatest danger for most of us is not that our aim is too high and we miss it, but that it is too low and we reach it. - Michelangelo (1475-1564)
Josh Smith wrote:
Why write beautiful code and then decorate it with ignorant boogers?
Variety is the spice of life? :-D
-
Josh Smith wrote:
Why write beautiful code and then decorate it with ignorant boogers?
Variety is the spice of life? :-D
hlmechanic wrote:
Variety is the spice of life?
In that case, I think I'll write all my comments in a mixture of ebonics and textspeak...
// yo bi4tch! dis cod3 be 4xin d4 us3r if d4 foo w4nn4 s4v3 dis shiznit?
:josh: My WPF Blog[^] The greatest danger for most of us is not that our aim is too high and we miss it, but that it is too low and we reach it. - Michelangelo (1475-1564)
-
Cool! I actually *do* have ascii art in all my projects source code comments at some point or another. I figure it will amuse someone some day down the road since no one else ever looks at the great majority of my code anyway. It serves a useful purpose in denoting blocks of commonly related code such as separating the Microsoft auto generated form code in c# winform projects from my own code:
// __ _ _ ___ ____ __ __ __ __ __ ___ ___
// / _)( )( )/ __)(_ _)/ \( \/ ) / _)/ \( \( _)
//( (_ )()( \__ \ )( ( () )) ( ( (_( () )) ) )) _)
// \__) \__/ (___/ (__) \__/(_/\/\_) \__)\__/(___/(___)
"I don't want more choice. I just want better things!" - Edina Monsoon
-
If you program in, say, C# do you sometimes put a semi-colon at the end of a statement and sometimes not? No, because the compiler rejects the code as being incorrect. In my opinion, the same standard for quality and accuracy should be applied to comments as well. Why write beautiful code and then decorate it with ignorant boogers?
:josh: My WPF Blog[^] The greatest danger for most of us is not that our aim is too high and we miss it, but that it is too low and we reach it. - Michelangelo (1475-1564)
-
Cool I luv the idea;). Do you know any simple program that creates me bigger texts(e.g. 3 lines by height) in ascii?
There are dozens of them online, here's the first one that google returned: http://www.network-science.de/ascii/[^] There are also plenty that can turn a gif or jpg into ascii which you can then paste in your comments as well. The possibilities are endless. ;)
"I don't want more choice. I just want better things!" - Edina Monsoon