Firstly, I am aware of this question:
Are there standard formats for comments within code?
But it didn’t answer mine. Whenever I write code, I always try to form a habit of ensuring that the comments are all consistent, but that is where I am sometimes indecisive about my code format convention. Especially since I want my code to be 80 or so lines wide.
Needless to say, a code format convention should be:
- Easy to read
- Easy to modify
And there may be different comment formats in different parts of your code, so it’s important to ensure they remain consistent and readable.
Here are some examples:
Single Line
// simple comment in lowercase
do_something();
// longer comment in lowercase. but now it doesn't seem like a proper sentence.
do_something();
// Longer comment in sentence case. But should we use sentence case for short comments too?
do_something();
// Like this one?
do_something_else(); // Or even this one.
Multi-line
// This code is very detailed and so I must continue further.
// Every time you start a new line you need to ensure you add //.
// If you finish your comment and forget to add something, you're screwed.
// You'll have to add your something and then make sure all the lines are 80 characters or less,
// and if they aren't you need to restructure all the lines below it.
/* This is better but you need to make sure it's properly indented each line.
Although you have to worry about those comment delimiters getting in the way.
At least it's compact. */
/* This comment seems better.
No need to worry about that last delimiter being inside your comment block.
*/
/*
Or maybe this is better?
At least it looks clean.
*/
/* GOOD FOR FUNCTION DEFINITIONS
Or maybe this is even better?
Who knows?
*/
Answer 1 – don’t, any time wasted argueing about braces is a waste of time.
Answer 2 – if you must, just pick one eg. http://www.possibility.com/Cpp/CppCodingStandard.html