-*- mode: text -*- The Hacker's Guide to Minor This is a nascent style guide for working on Minor. The present code is alleged to actually follow the conventions explained here; we welcome patches to fix any transgressions you find. * Naming conventions and hygiene - All C identifiers that are part of Minor's public interface should have names beginning with 'mn_' or 'MN_'. - All C identifiers that are not part of Minor's public interface, but still need to be extern or otherwise visible to client code, should have names beginning with 'mn__' or 'MN__'. - Use '_t' as a suffix for type names, to help Emacs colorize the code properly. - If a function takes an 'mn_call_t' as an argument, it should be the first argument, and it should be named 'c'. In declarations, the call argument need not be named. - Global references to exceptions should have names ending in '_exception'. - Global references to labels should have names ending in '_label'. - Functions that tag and untag heap objects should have names beginning with 'mn__tag_' or 'mn__untag_'. - A functions that checks whether a tagged value has a given type TYPE should be named 'mn__is_TYPE'. - In a struct defining a labeled object type, the first member holding the attached label should be named 'attached_label'. - Header files #included by users must not #include ; they should use the name '_Bool' for the boolean type instead. Internally, it's fine to #include and use 'bool'. - We tend towards using complete words in names: 'mn_get_exception', rather than 'mn_get_exc' or something like that. But we make exceptions where it would buy you a lot: 'mn_' instead of 'minor_', 'mn_ref_t' instead of 'mn_reference_t', and so on. - The header file describes other naming conventions that public functions' names are supposed to conform to. - If you're naming a file after a type, use the plural: 'bools.c', not 'bool.c'. Use the singular if there's only going to be one of them: 'heap.c', not 'heaps.c'. * Using C and POSIX - Minor code may use all the features of modern ISO C (ISO/IEC 9899:1999 (E), commonly called "C99"). - Avoid assumptions about the execution character set beyond those promised by ISO C. Do not assume the execution character set is ASCII, or some superset. (Naturally, you may assume that text documented to be in UTF-8 or Unicode is, in fact, in UTF-8 or Unicode.) - Manipulate text in Unicode whenever possible. - Prefer inline functions to macros. You may not need the static type checking, but some of us do. - Reasonable run-time sanity checks are great. Debugging time is precious. We can delete the checks if people complain about performance, and profiling shows that the checks are a problem. - Avoid functions that aren't defined by ISO C (ISO/IEC 9899) or POSIX (IEEE Std. 1003.1, 2003 Edition). You can bend this rule if you also do the necessary work to keep things portable, but keep in mind that autoconf stuff can be a distraction. - Use 'check' from gc/check.h, not 'abort' or 'assert'. * Commenting and documentation - Every header file representing a module's interface must fully explain how to use the module. In principle, you should be able to write code that uses the module to its fullest after reading only its header file. - Capitalize the names of arguments when referring to them in comments. The goal here is to resemble the output from 'makeinfo' (except for the dumb quotes, which are mismatched in modern fonts). - If a function takes a call object as an argument for the usual reasons, there's no need to mention that argument. - There's no need for a comment above a function if it's covered in a header file. - Functions private to a module and thus not covered by any header file should generally have complete comments above them, if it's not obvious what they do. - Every source file should start with a one-line comment summarizing its purpose. - If a source file breaks down into sections in a reasonable way, start each section with a form feed and a newline, followed by a one-line comment summarizing the section's contents. The #inclusions at the top of the file should be on a page by themselves. (This allows the Emacs Page Extensions package, page-ext.el, to produce handy file summaries that you can use to navigate the file.) * Basic formatting - Follow the GNU Coding Standard's indentation style. If you're using GNU Emacs, this is the default. - Keep lines no more than 80 columns wide. - Write incoherent sections like this: mn__begin_incoherent (c); { ... Do incoherent stuff ...; } mn__end_incoherent (c); - The #inclusions at the top of a file should be segregated into (up to) four groups, separated by blank lines, and containing no blank lines: + the #inclusion of "config.h" + #inclusions of header files that are part of ISO C or POSIX + #inclusions of header files for other packages that are not part of Minor (GTk+, for example) + #inclusions of Minor header files Use double quotes for the first and last, and angle brackets elsewhere. - Don't use tab characters for indentation. Tabs make patches look funny, especially when posted to mailing lists. In Emacs, set indent-tabs-mode to nil. - Place two blank lines between functions. - Don't use the grave accent character, `, and the apostrophe, ', as paired quoting characters, like `this'. A lot of GNU software does use them that way --- Emacs and Texinfo, for example --- and this use was supported by earlier versions of ASCII, but modern character sets haven't retained that characteristic, and the characters don't look paired on many modern fonts. Instead, just use 'apostrophes'. Or, in contexts where they'll actually work for most people and not just be annoying, use the Unicode "Left Single Quotation Mark" and "Right Single Quotation Mark". For more detail, see: http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html * Testing - The test suite should call every (implemented) function in the C API at least once. (The script 'gc/tests/untested' may help you find functions you've missed.) - Give tests for C API functions names like 'c-api-FOO'.