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.

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

1 Answers1

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).

Doc Brown
  • 206,877