Pkgsrc coding style
From NetBSD Wiki
This article describes why the pkgsrc files look the way they look, and what the reasons are.
Contents |
Makefiles
Comments
The first unescaped # character, and everything following it in a line, is considered a comment by make. For humans, these comments serve a lot of purposes. They provide a relatively low-level documentation on how things are done, why they are done, and how the code around the comment is intended to be used. They are also sometimes used for temporarily disabling code.
These different purposes should be visually distinguishable, so that people don't read the quirks of the implementation when they just want to know how to make use of the code.
Code that is commented out
To disable some code, prepend a # character directly before the code, without any space characters in between.
Interface descriptions
Each file should start with a few paragraphs describing what the file does and how it can be configured by the pkgsrc user and the package itself. The interface description ends at the first line that is completely empty (that is, contains not even a # character).
Since these interface descriptions are the API of pkgsrc, they need to be well written and suitable for their intended audience, that is, pkgsrc users (who may not be programmers at all) and package maintainers (who are more often, but not necessarily, programmers). Both these groups want to find the information they are looking for as quickly as possible.
Text layout conventions
The text is structured into paragraphs, which are separated by an almost-empty line (containing only a single # character). The first word of each paragraph is taken to be a help topic for make help if it is either completely lower-case or completely upper-case. Everything else is ignored.
Implementation comments
These comments should be embedded into the code, either in a line of their own, or at the right of the code they are documenting.
