In this post, I am doing something different. Above is a link to a great article on ‘Can Comments become Code Smells ?’ by Neal Ford. I would like to know your opinion on it and have a good discussion on the that. To start off, here are my views on the topic.
- Going through the article, lot of it makes sense especially for projects where the there are frequent changes in the code. The team should spend maximum time developing rather than on documentation. Documentation makes more sense when the code base is fairly stable.
- However for this to succeed the function names must be accurately describe their job, otherwise maintenance can quickly become a nightmare.
- With regards to documentation, the purist in me would like to avoid documentation altogether, but the realist in me would want good documentation in at-least the public APIs. Also my experiences with Open-Source software make me wary of undocumented or poorly documented libraries. I would even stick my neck out and go on to say a library is as good as it’s documentation.
What say you ?