General guidelines
The quvi project needs consistent and maintainable code. Below are some general guidelines to follow when you write new code:
- Do not exceed 80 char line length (ideally, keep the max length at 72-78)
- Use one-liners sparingly; do not try to pack everything together
- Use comments sparingly; the code should speak for itself
- Be wary of the word-wrap feature of the editor
- Do not write code that requires deciphering
- Use LF for newlines
Variables and functions:
- Use underscore-lowercase, not CamelCase (e.g. parse_stream, not ParseStream)
- Keep the function names short but meaningful (e.g. chk_stream_avail)
- One-character variable names are OK in simple (few lines) functions
- Split complex functions into multiple simple ones
- Keep the variable names short
Commit messages
- Prefer writing summaries of the changes, not life-stories
- Explain in detail, if you are making complex changes
- Keep the message lines under 80 characters
- Keep the oneliner brief but descriptive
The messages provide a written history for the project, making it easier to pick individual commits for a closer inspection. For example, when we have to track down a regression, or a look up a reason why something was changed at an earlier stage of the development.
The distribution files (e.g. ChangeLog and NEWS), and the release announcements, are generated from the git commit logs. This is another reason why the oneliners should be worded carefully.