The solution to this type of rigorous way of coding has already been provided as a methodology to writing software itself. And it has nothing to do with comments. The problem with comments is that they have NO impact on the way the product ultimately works. The best comments in the world cannot keep software from crashing when embedded within a pace maker. Or when measuring the electrical signals with a portable EKG.

We have two types of comments:

## Machine Readable Comments ##

Comment styles such as Javadoc, JSDoc, Doxygen, etc. are all ways of commenting the public interface a set of code provides. That interface may only be used by  single other developer (Proprietary code for a two person team), an unknown number of developers (e.g. JMS), or for an entire department. This code can be read by an automated process which then produces a different way of reading those comments, ala HTML, PDF, and such.

This type of comment is easy to create a standard for. It becomes an objective process of ensuring every publically invoke-able method, function, class contains the required comments. Headers, parameters, description et. el. This is to ensure that it's easy for another team to find and use the code.

## I'm doing something that looks crazy, but it's really not ##

These comments are here to help other's see WHY this code was written a certain way. Perhaps there is a numerical error in the processors the code is running on and it always rounds down, yet developers typically deal with code which rounds up. So, we comment to ensure that a developer touching the code understands why the current context is doing something would normally _seem_ unreasonable, but in reality was written that way on purpose.

This type of code is what causes so many problems. It typically goes uncommented and is later found by a new developer and 'fixed.' Thus breaking everything. Even then, the comments are only there to explain the WHY not to actually prevent anything from breaking.

## Comments cannot be relied upon ##

Comments are _ultimately_ useless and cannot be trusted. Comments do not normally change the way programs run. And if they do, then you're process is causing more problems then it should. Comments are afterthoughts and can never be anything but. The code is all that matters as that is all that's processed by the computer.

This may sound asinine, but bear with me. Which of these two lines really matters?

`// We don't divide by 0 in order to stop crashes.` 

`return 1 / n;`

In this example all that matters is that we have no idea what 'n' is, there isn't any check for n being 0 AND even if there was, nothing stops a developer from putting `n = 0` AFTER the check for 0. Thus, the comment is useless and nothing automated can ever catch this. No standard can catch this. The comment, while pretty (to some) has no bearing on the outcome of the product.

## Test Driven Development ##

What does have an outcome on the product? Industries in which the code being written can literally save or kill someone has to be rigorously checked. This is done through code reviews, code reviews, testing, testing, code reviews, unit tests, integration tests, trials, staging, months of testing, code reviews, and single person trials, staging, code reviews, testing, and then maybe finally going into production. Comments have nothing to do with any of this.

I would rather code that had NO comments, had a specification, had unit tests which verified the spec, studies of the outcomes of running the code on the production device, then well documented code that had never been tested, nor had anything to compare the code against.

Documentation is nice when you're trying to figure out WHY someone did something a certain way, however, I've found through the years that documentation is typically used to explain why something 'clever' was done, when it really didn't need to written that way.

## Conclusion ##

If you work at a company which REQUIRES every line be commented I GURANTEE at least two of the software engineers on the project have already written a auto-document program in Perl, Lisp, or Python which determines the general idea of what the line is doing, then adds a comment above that line. Because this is possible to do, it means the comments are useless. Find the engineers who have written these scripts to automatically document the code and use them as evidence to why the 'Comment on Every Line' is wasting time, providing no value, and potentially hurting.

On an aside, I was helping a close friend with a programming assignment. His teacher had set a requirement that every line had to be documented. So I can see where this thought process would come from. Just ask yourself, what are you trying to do, and is this the right thing? Then ask yourself; Is there any way to 'game' the system with this process? If there is, then is it really adding any value? One cannot automatically write unit tests which tests that code meets a certain specification, and if they possibly could, that wouldn't be a bad thing.

If a device has to work under certain conditions because it'll be inside a human, the only way of ensuring it's not going to kill them it years of testing, peer review, trials, and then NEVER EVER changing the code again. This is why NASA is / was still using such old hardware and software. When it comes to life or death you don't just 'make a little change and check it in.'

Comments have nothing to do with saving lives. Comments are for humans, humans make mistakes, even when writing comments. Don't trust the humans. Ergo, don't trust the comments. Comments are not your solution.