0

My professor today told me that I should comment my code (PHP & Javascript) in all caps…is there a substantive reason for this or is this an issue of best practice?

If so, why is it better to comment in caps over sentence case?

joshdcomp
  • 1,618
  • 3
  • 19
  • 26
  • 2
    There is no good reason to do this, and, with all due respect to the academic profession, your professor is either a little nuts or is trolling you. Or (like Adam suggests) you're misunderstanding his recommendation. – Michael Petrotta Apr 20 '11 at 04:08
  • 4
    The unvarying glyph heights of all caps render it less readable than using proper case. Is it possible s/he was instead talking about using all caps for constant names? e.g. http://stackoverflow.com/questions/130396/are-there-constants-in-javascript – mechanical_meat Apr 20 '11 at 04:09
  • This is actually subjective question and belongs on http://programmers.stackexchange.com/faq – Mike Atlas Apr 20 '11 at 04:12
  • @mikeAtlas: I'm confused, and asking others to explain an issue…doesn't that warrant posting something here? @Larry: It's not a troll…I'm just learning code grassroots-style, thus questions may come off as troll-ish. @adam, no, he meant after "//" to write my comment in all caps – joshdcomp Apr 20 '11 at 04:43
  • 2
    In the real world, commenting in all caps is highly unusual and unnecessary. Comments should be easy to read! However, you do need to earn the grade, so for your assignments for this prof, comment in all caps. – Mike Atlas Apr 21 '11 at 15:40
  • This is purely a style preference your prof has. While not necessarily a commenting worst practice (misleading or irrelevant comments are worse) it's not considered best practice. I would recommend Steve McConnell's Code Complete (http://www.stevemcconnell.com/cc.htm) if you would like a good guide to improving your programming practice. – Andre Artus Apr 27 '11 at 12:12
  • After 15 years of commenting in Sentence case I switched to all caps comments, and I will never go back. I like it because caps are hardly ever used in the rest of the code, so it makes the comments really stand out. My code is well-commented and because caps comments stand out so much, it's easier to quickly skim comments until I find the place where I need to actually make changes to the code. – Paul Slocum Jul 18 '13 at 05:11
  • @PaulSlocum You need to find yourself a better syntax highligher – josaphatv Apr 10 '15 at 23:14
  • in my opinion, if the comment is a full sentence starting with a uppercase letter otherwise lower case comments are the way to go. maybe the professor meant this as well. or he is stuck with old ways. – Ali Mert Çakar Jul 04 '23 at 13:34

1 Answers1

2

First, stylistic questions like this can be a little subjective, so there's not necessarily a clearly "right" or "wrong" answer. With that said, I've never seen that done in any professionally-written code, nor have I seen that practice recommended in any coding standard.

Consider the following paragraph (taken from here):

GIVEN THAT O'BRIEN SHOWS A HIGH LEVEL OF AWARENESS OF THE PARTY'S DECEPTIVENESS AND MALICE (E.G. THE FACT THAT HE ADMITTED TO BEING INVOLVED IN CREATING AND PROMOTING THE GOLDSTEIN MYTH), TO WHAT EXTENT DOES HE ACTUALLY BELIEVE IN THE SYSTEM HIMSELF? WHY WASN'T HE CONSIDERED A THOUGHT CRIMINAL? OR WERE INNER PARTY MEMBERS NOT ACTUALLY EXPECTED TO CONFORM TO THE PARTY'S BELIEFS TO THE SAME EXTENT THAT OUTER PARTY MEMBERS WERE AS LONG AS EVERYONE ELSE WAS CONVINCED THAT THEY DID? OR IS HE PRACTICING SOME FORM OF DOUBLETHINK?

Obnoxious to read, isn't it?

Here's the paragraph in "normal" text:

Given that O'Brien shows a high level of awareness of the Party's deceptiveness and malice (e.g. the fact that he admitted to being involved in creating and promoting the Goldstein myth), to what extent does he actually believe in the system himself? Why wasn't he considered a thought criminal? Or were Inner Party members not actually expected to conform to the party's beliefs to the same extent that Outer Party members were as long as everyone else was convinced that they did? Or is he practicing some form of doublethink?

The second is obviously way easier to read. That being the case, capitalizing the comments only makes them more difficult to read.

The only reason I can think of that someone might recommend that is to make it easy to distinguish from the code, but that hasn't been a valid reason for a long time (unless you're trying to write your code in Notepad or some other really awful tool) because modern IDEs fix that problem with syntax highlighting.

EJoshuaS - Stand with Ukraine
  • 11,977
  • 56
  • 49
  • 78