I made a few feeble attempts. starting a sentence without a capital letter - no way! Muscle memory and the habit of decades. But I don't get it. Is the sacrifice of correct punctuation really worth the gain? What, an extra tap on the Shift key? Which is how I suppose the practice started for real programmers, coding in volume? What about the untidiness of the rest of the comment? Are commas, semi-colons etc abandoned too? And the occasional multi-sentence comment?
I also don't understand you questions. There a few best practice rules for a good name convention but all of this is not defined by law. So basically you can write your code as you want, but it's probably not good to read for third persons which want to review your code.
It's a individual decision. There are programmers who using comments thrifty indeed. But in better organized project the documentation is generated by tools like doxygen which can increase the readablility instead of inserting tons of comments within the code.
You also have to consider that it can create a lot of effort if you want to documentate each function in detail. A lot of programmers want to create functional code and don't want to write big documentation "books". At the end it's a individual problem and in companies a question of the requirements of the management
You can see an example of the common style @Terrypin is referring to here:
Note that the "p" in "put" is not capitalized.
I think the style makes sense in the case of short comments that are not complete sentences. But with a complete sentence I would use proper capitalization and punctuation, and even more so for a multi-sentence comment.
I've vaguely noticed that some comments are not capitalised, I've never thought much about it beyond it being the style of the person who wrote the code. My comments are capitalised, and I notice those of many other people are too. Do what works best for you.
Some? I have a thousand or more sketches accumulated for learning and reference, from scores of sources, online and paper. (Must get around to some house-keeping) . I’d estimate the proportion with uncapitalised inline comments as about 99%.
Just had a look through sketches in Latest and have yet to find one that capitalises as I do.
I learned the hard way how important comments in my own code are. Several sketches I wrote a few years ago, now puzzle me completely why I did certain things the way I did them. Or making me to search in the datasheet what a particular register does.
For short comments only to clarify the function of a statement or register I don't capitalize. I save the capitals for names.
example:
ISR(USI_OVF_vect) { //interrupt service routine when USI timer overflows
USICR |= _BV(USITC);// toggle the SCL port by writing one to this bit
USISR |= _BV(USIOIF);// clear the USI counter Overflow Interrupt Flag
}
For longer text explaining what the sketch is for or why I do something I tend to write normal sentences, but put them in a comments block.
example:
/*************************************************************************
Attiny85 two tone beeper on SCL pin PB2 (mis)using only ADC and USI
Uses none of the 8-bit timers or watchdog timer)
Connect a passive beeper to SCL pin PB2
Connect a (10K) potmeter between GND<>RESET<>VCC
*************************************************************************/
And it makes it easier to share my code with others.
OK, so that shows you've paid it more attention than I have. I'm sure you will have noticed that I have written a few tutorials. If you read a bit further at the end of the tutorials you will see credits and thanks to the people who have helped me. When I write a tutorial I usually ask for help and feedback, because getting someone else's opinion is really, really helpful. One bit of feedback I am sure I have not had is 'don't capitalise your comments'.
If you read lots of topics on here you will find replies suggesting adding comments to code, you will find replies pointing out that the comments do not accurately indicate what the code does. I have yet to see a comment that says 'comments should not be capitalised', I challenge you to find such a comment.
Your code must comply with the rules of the language, C++, otherwise the compiler will tell you there's a problem with it, or worse, the compiler won't complain but you will get some weird problem when you run it. Comments are your own business, as I said before:
And don't worry about what other people will think. If the comments are clear and explain the code well people will think how nice it is to read well commented, understandable code, they won't fret over some capital letters, but if they worry only about the capital letters, then really, pay attention to someone else who doesn't.
Yes. When you type with two fingers, capital letters are a PITA. Since most comments are fragments, it does not make sense to hold them to rules meant for regular writing.
Worst: variables names using underscore characters. Especially if you use a few different tablets and each hides that character in a slightly different way.
Yea, Bar Sport. So, I’ll throw in. Seeing poor language practices in comments doesn’t bother me nearly as much as (allegedly) native English speakers posting nearly unintelligible questions and requests for (free) help in places like this forum.
My god, take some time to organize your thoughts. Express them in proper English paragraphs. Use complete sentences with proper capitalization and punctuation. While you’re at it, run the text through a spell checker before posting it.
You’re not texting your friends here; you should be communicating like a technical professional to other technical professionals.
