Comment styles

[Ninjakreborn]

it's wierd how many actually styles of comments there are.

 

Standard html <!-- comments -->

PHP

#

//

/* */

However after all these styles it's weird noticing different people pick different one's.

For example me personal I love // for single/double line, then I like # for sections, or really important

information. it's wierd the background on each one, and what languages they came from.

 

This is one major problem I have with CSS

they have /* */ style comments, which from my standpoint is the most annoying except for giant blocks of comments (which aren't really needed if there worded right)

In css, that comment style just makes it take longer to write CSS.

What are your favorite styles of commenting, what do you end up finding yourself using most of the time.

[ober]

Comments... what are those? 

[jcombs_31]

Honestly, who cares how you comment your code?  Your references to different methods are based on different languages.

 

But, typically a single line comment in most programming languages will use //

A multiline comment will typicall use /* */

 

This is no rule set in stone, use whatever method you are most confortable with.

[Nameless12]

I don't see the point in commenting that much I comment for http://www.phpdoc.org/ just so I can automatically generate documentation most people will probably call me stupid for this but I do not do any other commenting of any sort because I think updating out of date comments is a real time waster and any comment you write will end up becoming out of date eventually. I think planning ahead is great and documentation is good, but updating comments just annoys me too much not to mention the amount of monitor real estate they can take up.

 

And yes I am aware you can minimize them with some editors although I think Zend studios minimizing of comments is a bit buggy as working with code seems to make them want to expand and I have not found a way to set comments as hidden by default, but then again I have not exactly looked for this feature so it may exist and I just don't know about it.

 

EDIT::

If you write good code it should be easy to understand and not require comments as it should be obvious what it does this is another reason why I only like to comment return types and arguments

[Ninjakreborn]

Best on every article I have read.  There are many things with "coding quality".  I hear people around here passing around the same principles.  I wasn't asking a question about commenting.  I know the different styles, adn some about there background, I was more expressing opinions about then.  However I do feel it's a very important of good programming style is to implement comments.  It might be obvious to the person programming what everything does but to someone just starting, or someone who has to modify it, it is.  It is a very important aspect of coding/programming. 

 

The only thing I don't like commenting much is my CSS (which I do anyway), but that's because of the horrible /* */ which is awkward to type, and slows me down a bit each time.  So normally after it's over, I go through and comment sections, with some notes at the end, so I can have everything almost done before then.

 

How someone comments also reflects there overall style.  In my opinion, if they comment well you can tell they liked being organized.  If they like using // # they generally like things being quicker.  In php if you notice /* */ all over the place, they like taking careful time into there comments.

 

You can tell a lot about a person just by there commenting style.

[roopurt18]

Shame on any programmer that doesn't add comments.

 

I myself use // as often as possible, that makes it easy to go back and comment out large blocks easily.

 

I don't have any problems with the /* */ syntax, but then again I know c!

[Nameless12]

Shame on any programmer that doesn't add comments.

 

I myself use // as often as possible, that makes it easy to go back and comment out large blocks easily.

 

I don't have any problems with the /* */ syntax, but then again I know c!

 

Why I use phpdoc

1. intellisensing + phpdoc = very nice

2. phpdocumentor can use it to generate documentation

 

I do not believe someone such as your self would consider the above "proper" commenting, I do not consider it proper commenting. I think proper documentation should not be stored inside your source code in the form of comments and if you want to get another developer up to speed on your code\project or whatever UML and written documentation is much better at this then comments will ever be.

 

Why I don't believe in proper commenting

1. Versioning systems such as cvs\svn are better for storing comments\documentation directed towards changes in code

2. Uml and written documentation is easier to read and understand then being told to read the source code when asking for documentation.

3. If you typed code that is so cryptic that you need to comment it you should delete it and start again as good code should be clean and not cryptic

4  if you are reading someone else's code that has no comments and you do not understand it odds are you are not qualified to modify it unless the code was poorly written

5. classes\functions break stuff into manageable easy to understand chunks and phpdoc can help make this even more clear (i'm all for phpdoc after all)

 

If you have any reasons why you love comments that I have not taken into consideration I would love to hear it but I think I have taken everything into account. I am not advocating using minimal comments, you should write your code how you want\need to write it but the idea that it is shameful if you do not comment every every single little thing is just wrong.

 

comments != documentation

 

oh and outside of functions\classes in css for example comments become more useful but 99++% of your code should be functions and classes to begin with, with an exception of tpl files.

 

 

[cmgmyr]

i try and comment as much as i can, it's even more important when you are handing it off to someone else...

 

I use // for little comments and /* */ for larger ones (obviously). I don't think it really matters what style you use...just if you do it or not. It's a pain to comment everything, but it will help you in a few months when you have to change something in your script and you don't remember where everything goes or what it does...

[roopurt18]

1. Versioning systems such as cvs\svn are better for storing comments\documentation directed towards changes in code

These systems are better for storing significant changes to the overall file, not necessarily the nitty gritty of what's happening deep down within a function.

 

2. Uml and written documentation is easier to read and understand then being told to read the source code when asking for documentation.

Yes, they are.  But certain types of information just doesn't belong in a UML diagram or even code documentation.  If every possible bit of documentation was to be written within UML you might as turn UML into a self-documenting programming language.

 

3. If you typed code that is so cryptic that you need to comment it you should delete it and start again as good code should be clean and not cryptic

Wrong.  Code doesn't have to be cryptic to be difficult to read.  Even with the best naming conventions, best use of classes and functions, best indentation, etc. a block of code can become difficult to read if it represents an involved process and especially if it represents a small step nested deeply within a complicated process.  Now you can argue that the steps taken in performing the process should be kept elsewhere in documentation and I might even agree; but there are still going to be minor issues worth documenting in the code but leaving out of the main documentation.

 

4. if you are reading someone else's code that has no comments and you do not understand it odds are you are not qualified to modify it unless the code was poorly written

If the code was poorly written and had included a few comments here and there, it'd probably take less time to rewrite.  Worst argument I've heard in a while though.

 

5. classes\functions break stuff into manageable easy to understand chunks and phpdoc can help make this even more clear (i'm all for phpdoc after all)

Yes, yes they do.  There's different types of documentation.  There's documentation written for the people who use the class, i.e. the kind that phpDoc generates.  Then there's documentation written for the people who maintain the class, i.e. the kind you store in CVS change logs, UML diagrams, and comments.

 

<?php
  if(func1() || func2()){
    // do one thing
  }else if(func3()){
    // do another
  }
?>

There's nothing cryptic or difficult about that code to understand, it's a simple if statement.  But let's say that func2() must always be called after func1() and func1() has to be called before func3() due to the operations performed by each.  6 months later when you revisit that code, or when a new employee looks at it next week, a simple:

<?php
  // func2 always after func1, func1 always before func3
?>

in front of that if block can potentially save a ton of time, at the mere expense of the 3 seconds it took to type.

 

If you fail to write comments entirely, I have to wonder what's the largest project you've worked on with multiple individuals and how much of your code you need to maintain 6 months after you've written it.

 

[Ninjakreborn]

Alot of very good points, thus supporting the idea that commenting styles have a wide range of followers.  Some people do it, some people don't.  Some people love one way, but hate another.

[Nameless12]

I never said commenting was evil I just think it is over emphasized I think when you said code is easier to rewrite if you have comments. I think that you meant code is easier to fix with comments. I did not mean this, I meant rewrite the code not fix.

 

As I said I am all for phpdoc, I just hate having comments spread through out the body of a class or function. phpdoc covers all the points you made that I agree with. the areas I dont agree with are the spreading of single line comments throughout the body of a function\method without very good reason

 

If you use functions properly stuff should be short enough that you do not need comments spread throughout the function body. This reminds me of a term I heard ages ago "god classes". "god functions" are just as bad...

 

comments near if statements almost always result in repeating your self. in a way that is not useful and a waste of time.

 

I get the impression that when I say rewrite you instantly think rewrite the web page I do not mean that at all, I mean rewrite the function or method and rewriting functions is usually quick and a lot easier than trying to fix some ugly code.

 

My point was not that my way is better, but that my way is far from wrong. There is nothing wrong with leaving out comments as long as you document your work and if you are not going to document your code its probably not even worth the wasted time of adding comments in the first place. Some source code can be 50% comments and that is just ridiculous.

 

I will leave you with a quote from wikipedia

 

"Don't document bad code – rewrite it" (The Elements of Programming Style, Kernighan & Plauger).

[roopurt18]

I never said commenting was evil I just think it is over emphasized I think when you said code is easier to rewrite if you have comments. I think that you meant code is easier to fix with comments. I did not mean this, I meant rewrite the code not fix.

 

Fixing and rewriting are often the same thing.  Anywho, I meant what I said: Code is easier to rewrite (or consequently fix) if comments are provided.

 

Anyways, there's no point carrying this conversation on.  I just hope I never have to debug, fix, or rewrite anything written by you.

[neylitalo]

phpDocumentor is simply amazing - I've got a vim plugin that automagically documents classes, functions, and entire documents with a simple Ctrl + P, and I wrote a simple shell script to generate the documentation.

 

I've attached both the plugin and the bash script used to update the documentation, in case there are any vim enthusiasts here.

 

To activate the vim plugin, put it in ~/.vim/plugin/ and put these lines in ~/.vimrc:

 

inoremap <C-P> <ESC>:call PhpDocSingle()<CR>i
nnoremap <C-P> :call PhpDocSingle()<CR>
vnoremap <C-P> :call PhpDocRange()<CR>

 

[attachment deleted by admin]

[Stopofeger]

Well comments.

I actually make very fewer comments. And only because i forget what i thought or changed quickly so i need make them sometimes to make me aware what happened.

 

as far as //,#,/**/ goes. obviously // is the easiest to type. But doc generators such as doxygen uses /**/ to generate docs so probably if i make a big soft sometimes that needs api docs, i wud use it.