[LLVMdev] LLVM maintainers, code reviews

[Jan Sjodin]

> >>> I'd like to do more similar ones in the future, and  encourage other 
>contributors to also write other blog entries in  general.

> >>
> >> Hi Chris,
> >>
> >> After  discussing these topics in the dev meeting, I also have some  input.
> >>
> >> First, blog posts are great for communicating  changes and maybe
> >> outlining design decisions, but these decisions  change over time, and
> >> the posts become obsolete.
> >
> >  Right.  Jan was specifically asking about the "why things were decided and 
>what  the tradeoffs were", which is an inherently a "moment in time" sort of 
>thing.   IMO, this is perfect for a blog post.  Blog posts have the advantage 
>that they  are explicitly dated.
> 
> I'm a big fan of putting such things *in the code*  as comments.  It
> does logically go with that bit of code, after  all.

I agree that a blog is probably one of the better ways of documenting these 
things. A lot of discussions happen on the mailing lists and irc, and the person 
who is supposed to do the work (and probably initiated the discussions) could 
gather all the information and post it so that everyone can get the same 
information. With the proper tagging it is easy to find posts related to a 
specific module/library. Having a collective journal for the projects makes it 
possible to see if the code has diverged from the original design. It is useful 
to have a record of how people were thinking about the code and not only what 
they did to it. A blog post that is dated it is more likely to be treated with 
some skepticism if it very old, compared to Wiki and comments in code, which 
give the illusion they are up-to-date and accurate. That does not mean I am 
against comments in the code, but I like comments to explain more detailed 
things about the implementation. The only thing accurate is of course the code 
itself. We don't want to write blogs or comments unless it is needed, and 
finding a good balance is difficult. 


- Jan