Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

What information to put in comments at the top of a sourcecode file?

Tags:

comments

What information do you consider worth to put in the comment at the beginning of a sourcecode file?

All I could think about was the name of the author and perhaps the date the file was created (although I'm not to sure if there is any useful value to this information).

[EDIT] To clarify, I don't mean comments before a class, but at the first lines of the file, before include statements and what else. Like

/**
 * Author:    Name
 * Created:   11.05.2009
 * 
 * (c) Copyright by Blub Corp.
 **/
like image 508
Michael Klement Avatar asked May 11 '09 06:05

Michael Klement


People also ask

How do you comment in source code?

The single line comment is //. Everything from the // to the end of the line is a comment. To mark an entire region as a comment, use /* to start the comment and */ to end the comment. * This is a block comment.

Should comments be above or below code?

Your comments should rarely be longer than the code they support. If you're spending too much time explaining what you did, then you need to go back and refactor to make your code more clear and concise.


2 Answers

  • Copyright
  • Original author(s)
  • License (if it's open-source)
  • One-line purpose statement or description
  • Further overall documentation and usage examples

Edit: Changed Author(s) to Original Author(s)

like image 120
a paid nerd Avatar answered Dec 10 '22 18:12

a paid nerd


What to put in the file header:

  • Library/component that source code is part of
  • Copyright details
  • Brief and meaningful description of class(es) in source file

What NOT to put in the file header:

  • Anything that duplicates low level logic which is part of the code itself. This can lead to maintenance problems if it isn't updated when the source code changes.

  • Author name(s). Why?

    • In the world of revision control systems, while there may be an initial author of some code, eventually ownership becomes blurred. This is especially true when code enters the maintenance phase of the life cycle where owners can change regularly.
    • All code eventually becomes "community wiki" after enough changes ;-)
    • Would you want your name associated with all of the code forever, knowing full well that you will not be responsible for the code until its death?
  • Creation and last changed dates. This is for similar reasons as list above. Revision control includes this information - why duplicate it in the header, making more work for yourself and risking leaving inaccurate information in the comment when things inevitably change?

like image 28
LeopardSkinPillBoxHat Avatar answered Dec 10 '22 20:12

LeopardSkinPillBoxHat