summaryrefslogtreecommitdiff
path: root/doc/coding-standard.tex
blob: 23cf445e4728d2e5aa395bb1711542176f265157 (plain)
  1. \documentclass{article}
  2. \usepackage{metatron}
  3. \title{LedgerSMB Coding Standards}
  4. \author{The LedgerSMB Development Team}
  5. \begin{document}
  6. \maketitle
  7. \tableofcontents
  8. \section{Introduction}
  9. Consistent coding style contributes to readability of code. This contributes in
  10. turn to fewer bugs and easier debugging.
  11. While consultants which implement custom solutions for their customers are not
  12. required to follow these coding guidelines, doing so will likely contribute to
  13. efficiency of the project and, if desired, the likelihood of having the changes
  14. accepted in the main source tree.
  15. \section{File Organization and Whitespace}
  16. Files should be organized according to three principles: atomicity, performance,
  17. and readability. While there is no stated maximum file size, there is no reason to
  18. group large amounts of code together when only a small subset of that code will
  19. be executed on any given run of the program. Similarly, core API for a single
  20. data structure entity may be grouped together even if each run may touch only a
  21. small part of the code so that these functions can be maintained together in a
  22. logical way.
  23. Nested blocks of code should be indented with a single tab. This way,
  24. programmers can adjust the tab width of their editors to their preferences.
  25. Lines longer than 79 characters are not handled well by many terminals and
  26. should generally be avoided. Continued lines should be indented by one more tab
  27. than either the line above or below (i.e. if the line above is indented by two
  28. tabs and the line below by three, indent the continued segment by four).
  29. Lines longer than 79 characters cause problems in some terminals and should be
  30. avoided.
  31. \section{Comments}
  32. In an ideal world, the code should be sufficiently readable to be
  33. entirely understandable without comments. Unfortunately, this sort of
  34. ideal is seldom attained. Comments should be used to annotate code
  35. and add information that is not already a part of code or programming
  36. logic itself.
  37. Comments may include arguments and return values of functions (for
  38. easy reference), a summary as to why a particular design choice was
  39. made, or a note to alert future programmers that a particular chunk of
  40. code deserves additional attention. Comments should not, however,
  41. merely indicate what the program is doing or how it does something.
  42. If such comments are required, that is a good indication that a block
  43. of code requires rewriting.
  44. Additionally it is a good idea to provide a brief description at the top of each
  45. file describing, in general terms, what its function is.
  46. \section{Function Organization}
  47. Functions should be atomic. While there is no maximum length to functions, long
  48. functions may be an indication that a function may be non-atomic.
  49. In general, when more than one line of code is being copied and
  50. pasted, it should instead be moved into its own function where it can
  51. be called by all entry points.
  52. \end{document}