2

I want to know if including a file summary comment at the beginning of each file is a good way of knowing what each file does or is there a better way.

5
  • Which programming language are you using? In a Bash script, file comments would be helpful, but in C# I would expect to see XML comments on the class declaration.
    – Dan Wilson
    Oct 2, 2018 at 20:18
  • Mostly python, also java and bash.
    – user157989
    Oct 2, 2018 at 20:20
  • I think the obvious answer is yes. If a generally accepted documentation system is available (Docstrings, Javadoc, etc.) then I would use that.
    – Dan Wilson
    Oct 2, 2018 at 20:23
  • Possible duplicate of "Comments are a code smell"
    – gnat
    Oct 2, 2018 at 20:29
  • 2
    Specifically for Python, then yes, module-level docstrings are recommended (this ties into the interactive help() system and is often used for auto-generated documentation). But in general, this is a matter of personal preference. Such comments might get out of date over time, which renders them worthless at best and confusing at worst. The file's name should already be a decent indication of the content.
    – amon
    Oct 2, 2018 at 20:58

1 Answer 1

1

A high-level summary comment at the beginning of any code unit like a module, class or package, explaining the purpose and/or responsibilities of the unit is definitely a useful way of commenting in almost any programming language I know. In many languages, it is not uncommon (and in some cases like Java it is even mandatory) to have a 1:1 correspondence between code files and such code units, and there the answer is IMHO "yes, absolutely".

However, I recommend you better use a mental model of summary comments per logical unit, not per physical (file) unit, this will often make more sense. Be aware that lots of programming languages allow multiple units per file, or have certain conventions to distribute one unit over a number of files (for example, splitting a C++ class into a header and an implementation file).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.