On Wed, Mar 18, 2009 at 3:16 AM, Konstantin Osipov <kostja@stripped> wrote:
> * Mats Kindahl <mats@stripped> [09/03/18 11:32]:
>> One thing that I am missing is a rationale... it is very hard to
>> make a decision on why a particular style should be implemented,
>> unless there is some kind of reason to why it should be
> Let's if I understand the rationale correctly:
> The rationale for the first is simplification of the rules.
> The rationale for the second is increased code clarity (for the
> cost of increased maintenance burden and some difficulties with ctags).
Documenting interfaces reduces the maintenance burden. Code is written
a few times and read infinitely many times.
Comments about the implementation may be incorrect but are still
better than no comments as they give me a clue about what the code is
trying to do at some point in time.
InnoDB is a great example of how to write code that others can read
and understand. InnoDB also happens to get large changes from the
community. It has great documentation for interfaces, module comments
at the start of source files and structure (source and headers are
split into multiple files by functionality), modules use separate
subdirectories. It also names variables and functions consistently
using module prefixes (trx_, buf_, ...).
> MySQL Internals Mailing List
> For list archives: http://lists.mysql.com/internals
> To unsubscribe: http://lists.mysql.com/internals?unsub=1