1

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.

  • 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 '18 at 20:18
  • Mostly python, also java and bash. – Arturo Oct 2 '18 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 '18 at 20:23
  • Possible duplicate of "Comments are a code smell" – gnat Oct 2 '18 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 '18 at 20:58
2

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, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.