unrealircd

- supernets unrealircd source & configuration
git clone git://git.acid.vegas/unrealircd.git
Log | Files | Refs | Archive | README | LICENSE

coding-guidelines (5760B)

      1 Rules about patches & modifications to UnrealIRCd
      2 
      3 1. When making a change, always add a small description in the commit log.
      4    Don't forget to mention the bug# and credit the reporter (if any).
      5 
      6 2. If new files are made, they must contain proper copyright headers.
      7 
      8 3. Each bug or feature should have a bug# so people can have a discussion
      9    about it. This has a few implications (read!!):
     10    * People must report bugs/feature requests to bugs.unrealircd.org and
     11      not on IRC, e-mail, etc.
     12    * That means other people can see the bug# and comment on it. This means
     13      discussion is easy to read back for each issue and not spread between
     14      several IRC logs.
     15      Furthermore, by using the bugtracker instead of directly committing,
     16      people could point out that there might be a better way to do things
     17      than you originally thought, or it might be that other devs don't like
     18      it at all.
     19    * If a head coder has 'acknowledged' or 'confirmed' the issue or stated
     20      in a comment that it's OK to implement, then any dev may take the issue.
     21      The dev should change the status to 'assigned' and work on it, then
     22      commit and change it to 'resolved', set 'fixed in version' to the
     23      correct release, and add a comment pasting the relevant commit log.
     24      Of course other guidelines, in particular rule #7, still applies.
     25 
     26 4. If you don't have direct write access to the repository then you can
     27    submit changes as as PR on github. It is very much preferred to also
     28    have a bugs.unrealircd.org entry for it as well (see previous item).
     29 
     30 5. For the stable branch, in general, only commit changes that have an
     31    associated bugid# and/or were discussed.
     32    For branches currently in development (alpha/beta) there's more freedom
     33    and if you think the change will be small and is fine without a
     34    discussion then feel free to commit.
     35 
     36 6. Regarding reidenting, restructuring or other major code cleanups: please
     37    discuss before doing so. The other devs might not agree with you on the
     38    particular cleanup you have in mind which would result in another
     39    clean-up-the-cleanup commit.
     40    You may, however reindent and clean up individual sections when you are
     41    working on fixing a particular bug# or implementing a new feature. In fact
     42    you're encouraged to do so if the code is confusing without it. However,
     43    obey the style of Unreal's code (mostly outlined in this document)
     44    and do not introduce yet another (new) style. Also, be careful with doing
     45    any cleanup: if you're unsure in any way about the use of something,
     46    or something that looks redundant on first sight, then look more
     47    carefully... it might indeed be useless and/or redundant, but it might
     48    also be a subtle thing that can create great bugs when 'cleaned up'.
     49 
     50 7. During the Release Candidate stage (from RC1 until the final release)
     51    only the head coder may commit directly, all others should ask and
     52    present their patch before committing. Yes, even if you are changing
     53    only 1 line of code or text.
     54 
     55 9. UnrealIRCd should compile on all supported operating systems and
     56    platforms, using GCC 3 or higher on *NIX, and Visual Studio 2008 or
     57    higher on Windows. This means you cannot blindly use all C99 extensions.
     58 
     59 10. Coders must test their code before committing.
     60 
     61 11. /*  
     62      * These kind of comments
     63      */
     64  
     65    NOT
     66  
     67    // These kind of comments
     68 
     69 12. 	if (something == 1) 
     70    	{
     71 		moo; /* comment */
     72 		/* This does what what what */
     73 		cow(go(moo));
     74 	}
     75 	
     76 	NOT 
     77 	
     78 	if (something == 1) {
     79 	}
     80 	
     81 13. Do not touch version.c.SH or version.h, unless you are a head coder.
     82     If you need a credit in, contact us
     83    
     84 14. Protocol changes must be discussed before making patches for it.
     85 
     86 15. We do NOT rip people off. If we use other people's code, it MUST be
     87     properly credited.
     88 
     89 16. We use tabsize 8 and we use tabs AND NOT SPACES.
     90     Some code is old and horrible and has a mix of tabs and spaces used for
     91     spacing, that's something we do not want to have ;)
     92 
     93 17. Be careful about overflows. Do not do any unchecked string copies.
     94     Instead of strcpy, strcat and sprintf/ircsprintf, use the following
     95     functions: strlcpy, strlcat, snprintf/ircnsprintf.
     96     If you are copying/writing character-by-character or word-by-word in a
     97     loop, eg using *p++ = x; then be very sure about your size counting.
     98     Often it's better to avoid such code altogether, by simply using
     99     strlcat for everything.
    100 
    101 18. Speed.  When optimizing or writing code, keep in mind that readability and
    102     stability comes FIRST, and after that comes speed. So we'd rather prefer some
    103     readable code (even if difficult) over some odd highly optimized routine which
    104     nobody understands, is difficult to extend, and might have several bugs.
    105     As mentioned earlier: use ircsnprintf, not snprintf (this is because
    106     ircsnprintf is optimized for simple strings like the ones we use).
    107     ircsnprintf calls snprintf when it finds a (non-simple) format specifier it
    108     can't handle.  Simple format specifiers do not have prefixes other than
    109     h and l.
    110 
    111 19. Initialize your structs and use the proper memory calls.
    112     In UnrealIRCd we use safe_alloc, safe_free, safe_strdup and safe_strldup.
    113     Do NOT use malloc, calloc or strdup.
    114 
    115 20. Comment your code! This should speak for itself...
    116     Put comments wherever you think they are needed, to aid any further coders
    117     with reading your code.. and, in fact, it will aid yourself as well if you
    118     would look back at your code 2 years later.
    119     If there's some obscure pitfall, DO mention it! Don't just "hope" a next
    120     author will see it like you did.
    121 
    122 21. Use enums whenever possible, rather than #define constants. Besides making
    123     things more clean, it also aids debugging.