Changes between Version 32 and Version 33 of Commentary/CodingStyle
- Timestamp:
- 04/24/11 15:00:50 (2 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Commentary/CodingStyle
v32 v33 8 8 The general rule is to stick to the same coding style as is already used in the file you're editing. If you must make stylistic changes, commit them separately from functional changes, so that someone looking back through the change logs can easily distinguish them. 9 9 10 == Comments and commit messages == 10 == Comments == 11 === Comments and commit messages === 11 12 12 13 Commenting is good but … … 54 55 (Commit messages can nevertheless contain substantial information, but it is usually of a global nature. E.g. "This patch modifies 20 files to implement a new form of inlining pragma".) 55 56 56 == Comments and examples==57 === Comments and examples === 57 58 58 59 When writing a comment to explain a subtle point, consider including an example code … … 79 80 * Cite a test case in the test suite that illustrates it 80 81 81 == Longer comments or architectural commentary==82 === Longer comments or architectural commentary === 82 83 83 84 Comments with a broad scope, describing the architecture or workings of more than one module, belong here in the commentary rather than in the code. Put the URL for the relevant commentary page in a comment in the code itself, and also put URLs for all relevant commentary pages in a comment at the top of each module. … … 99 100 pragma; you are encouraged to remove this pragma and fix any warnings when working on a module. 100 101 101 == To literate or not to literate?==102 == Literate Haskell == 102 103 103 104 In GHC we use a mixture of literate ({{{.lhs}}}) and non-literate ({{{.hs}}}) source. I (Simon M.) prefer to use non-literate style, because I think the {{{\begin{code}..\end{code}}}} clutter up the source too much, and I like to use Haddock-style comments (we haven't tried processing the whole of GHC with Haddock yet, though). 104 105 105 == T o CPP or not to CPP?==106 == The C Preprocessor (CPP) == 106 107 107 108 Currently we pass all the compiler sources through CPP. The -cpp flag is always added by the build system. … … 139 140 Also, it is necessary to avoid certain language extensions. In particular, the {{{ScopedTypeVariables}}} extension must not be used. 140 141 141 == The source file ==142 == Walk-through of a sample source file == 142 143 143 144 We now describe a typical source file, annotating stylistic choices as we go.
