Are there standard formats for comments within code? [closed]

Answer 1

Comment on the line above the code (block) that does what you're describing

// This is a comment.
Some code goes here

Avoid doing stuff like

// ----------------
// IMPORTANT COMMENT
// ----------------

And I avoid using the

/* comment */

And perhaps most importantly, clean up comments! A comment that describes non-existent functionality is worse than no comment at all.

Answer 2

You might want to at least consider using standard comment formats for the PHP Reflection Class: https://www.php.net/manual/en/reflectionclass.getdoccomment.php

My sites compress html so a comment like // comment here in JS will crash the java script. The specs for using // in PHP is only supposed to be a "short comment" ie: one line. Personally I don't think they should be used for more than one line.

Using them also makes it impossible to compress - or a lot harder to compress than what it should be.

Lastly.

Human interpretation is NOT absolute - a computer code is :)

So if you have a code that needs to or should be read - (Go Nasty) and don't comment it. ie: Force the reader to read the code rather than you relying on their interpretation of your comment.

Answer 3

(* Modula-2 comments go like this *)

Answer 4

There can be religious wars on this subject.

What I try to do, that doesn't cause too much warfare, is

 // explain the purpose of the following statement in functional terms
... some statement ...

The idea is, if I run the code through a program that deletes everything except the comments, what is left is pretty good pseudocode.

Something that's useful as a way to comment out code that you think you might need again is:

 /*
 ... some code ...
/**/

then modify the first line - either delete it, or change it to /**/

 /**/
... some code ...
/**/

Answer 5

/* I will sometimes write
comments like this */

Answer 6

I prefer commenting this way for function

/**
 * Activates user if not already activated
 * @param POST string verificationCode
 * @param POST string key
 * @return true on success, false on failure
 * @author RN Kushwaha <rn.kuswaha@gmail.com>
 * @since v1.0 <date: 10th June 2015>
 */

public function activateUserAccount() {

//some code here

}

I use single line comment for code descriptions like

//check if verificationCode exists in any row of user table
code here