Documentation History – Origin of ‘Readme’

What are the key aspects and contents of a good coding standards document?

1. Being supported by tools which enable automated checking of the code. If I know that I can't commit to version control any piece of code which doesn't match some rules, I would be encouraged to follow those rules in my code. If, on the other hand, some fellow programmer have written somewhere that I need to follow a rule, I don't give a crap about those rules.

2. Being well thought-out, instead of being your personal opinion. You don't plainly say: "from now on, we don't use regions any longer, because I don't like regions." Rather, you would explain that regions encourage code growth and don't solve any major problem.

   The reason is that in the first case, your fellow colleague would answer: "well, I like regions, so I would still use them". In the second case, on the other hand, it would force people who disagree to come with constructive criticism, suggestions and arguments, eventually making you change your original opinion.

3. Being well documented. Lack of documentation creates confusion and room for interpretation; confusion and possibility of interpretation lead to style difference, i.e. the thing standards want to suppress.

4. Being widespread, including outside your company. A "standard" used by twenty programmers is less standard than a standard known by hundreds of thousands of developers all around the world.

Since you're talking about StyleCop, I suppose that the application is written in one of the .NET Framework languages.

In that case, unless you have serious reasons to do differently, just stick with Microsoft's guidelines. There are several benefits in doing it rather then creating your own standards. Taking the four previous points:

1. You don't need to rewrite StyleCop rules to fit your own standards. I don't say it's hard to write your own rules, but if you can avoid doing it, it means you have more time doing something useful instead.

2. Microsoft's guidelines are very well thought. There are chances that if you disagree with some of them, it might be because you don't understand them. This was exactly my case; when I started C# development, I found a few rules totally dumb. Now, I completely agree with them, because I finally understood why they was written this way.

3. Microsoft's guidelines are well documented, so you don't have to write your own documentation.

4. New developers who will be hired in your company later may already be familiar with Microsof's coding standards. There are some chances that no one will be familiar with your internal coding style.

The author of the blog post was trying to make a point about how the Agile Manifesto emphasizes "working software over comprehensive documentation", and that when you do this, you risk losing the information about how software is supposed to work.

What's needed, whether it's Waterfall, Rational Rose, Agile, or some other SDLCM, is a "statement of purpose". It is some textual description of what is to be done, and why, at a detail level fine enough in the right areas that a developer can take this description into the team room as his "requirements", and produce correctly-behaving software as a result of his development efforts, guided by whatever methodology he or his team or managers see fit to follow.

In Waterfall, this is the Requirements Document. It's all defined, in detail, up front, before development begins, and if it changes while the project is out for development, development stops and the team reverts to the "design" phase.

In UML/Rational Rose, this is a "use case narrative". It describes what the "actor" (a person in a specific business role, or an external automaton such as another program) will do that should trigger some action, and what will happen within the system as a result of this action.

In Agile, this is a "user story", the exact form of which can differ depending on the exact flavor of Agile, but the two I've seen are similar to a UML "use case narrative" and a slightly different approach: "As a... I want... so that...". Similar to a use case in that the actor and the basic action are mentioned, but the addition is an integration of the business need into the context of the story, so when designing the solution, the development team can keep the business need in mind.

None of these is a "readme", and frankly I wouldn't want to read a readme that was written in the way the blogger suggests; it will be long, it will be ordered only according to the order in which the developer added the requested features, and it will be written by a developer, who will have his own perspective on what he's adding or changing and why that may not coincide with the perspective a user would have.