Source Code and comments for prototype development

Question

I'm involved in a prototype development. We can't say that it's completely prototype development. It's partially following the processes defined within the organization. As far the customer concerned it's a prototype development.

The problem is documentation. We don't have any time estimated and scheduled to prepare the architecture design and detailed design. However I've created an architecture for the system and created a simple document explaining the architecture and core components etc. as it necessary to shared between the team members and the newbies coming to the project. All other implementation details are reside within the code. For example, we're using lot of image processing algorithms, which are not officially prepared as a document. Everything resides within the code and the brain which created it. We can't ensure that a particular resource is always available in the organization or can't have him/her forever for that particular tasks.

My question is, how detailed should be the comments inside the code. The code will appear to be junk if it's overloaded with comments, but it's necessary to keep the source readable and maintainable for some more time. Later it will be turned to be a product.

Answer 1

Comments mostly useful when code is not speaking for itself.

Also it's useful to have a description of methods in case they will be shorter or more human readable than code itself.

Answer 2

A good test for wether a methods needs a comment is to pretend you didn't write the code (or if you have someone who didn't write it that would be even better) go through the code and see if it makes sense. Anything which stands out as not straight forward should be commented further.

This is really hard to do if you wrote the code yourself but since you have a team take some time to have your team review the other peoples code. This will will also help spread the knowledge about the code base so when you loose your resource at least others on the team will have seen the code.

Even though you have classified this code as prototype my guess is when you transition out of prototype phase that your not going throw away the existing code and start from scratch. Your going to take your current code and enhance it. So the comments and documentation should be good enough to assist in this.

The idea of prototype code is a fallicy. You have code which is production ready and code which is not.

Answer 3

Prototypes tend to be research code and as such you need to document as much as you can. Software prototypes unlike physical engineer projects tend to actually go into production. As such when the operations group gets your prototype they are going to be cursed at not understanding anything in the newly converted production system.

there are also patent/ip considerations to be considered as well. I've been apart of projects where simple dates in comments were significant in documenting the date of invention. This is significant in the abscence of any other documentation such as engineering logs, architecture descriptions etc.

Answer 4

I feel it's best to aim for high-quality code if I'm spending more than a couple of weeks on something, and that rather than leaving out quality it's best to omit (or mock) the non-essential functionality. Since you're aiming for an eventual product, it seems best to do this on your project. You'll hone your skills in producing high-quality code, and you'll increase the liklihood that components of your early system will make it into the product.

On comments, you should try hard to pick self-commenting variable and method names and use clear algorithms, and then provide comments for the classes, methods, and less obvious parts of your code. Generally putting good comments in your code is not a waste of time: the act of commenting makes you think about your code more intensively, and helps you find API design problems, bugs, future "TODO" items, and so on.

Answer 5

Conflicting statements in your question.
A prototype is an experiment / spike : learn something that you're not 100% sure will work out/ proof of concept. A prototype should be built to shed some light on a relatively high risk small scope portion of the system.
In the ideal case, you build a prototype, learn something and then chuck it. Build a better system leveraging your new found learning.

Now to my point, if we mean the same thing when we say 'prototype', you don't need architecture (unless you're prototyping a specific arch. pattern..) or 'heavy duty production strength' comments. Just do whatever you need to drive the nail through the board and get it done. At the end, document and share what you learnt for the benefit of your colleagues.

Your last line is scary... If you can stop coding for a while, book a conf room, pick up a copy of the Mythical Man Month and focus on the section which states 'Plan to throw one away, you will anyway.' Beware the day your 'prototype' gets promoted to 'Root Source' on your VersionControlSystem. Comments would be the last of your worries..