As an application architect, I constantly want to make sure that the "construction work" is going just fine. As I go through checklists of requirements, I can verify if we have code coverage over the system components and design specifications completed. When I feel we don't, I have to dig in to the internals and perform code/feature reviews with engineers. Even if we do have complete coverage, as time permits, I'll review code and provide tips on how to be better engineers for some and learn from others. In either case, I use the code reviews and "comments" together as a method to ensure that the code reflects the algorithms and improve future maintainability of the system.
I've always stressed commenting and, regardless of what some programmers might say, feel that it is essential to proper development when used the right way. Used the wrong way, a developer may feel that it is just another thorn in your side. The following methods are two of my favorites ways of exploiting comments in software engineering:
Aiding the Test-Driven FrontierI'm a big fan of the test-driven approach. As I write my stubs, I provide complete documentation of the software unit that I am planning to build. Along with the documentation for the stub, I'll write the algorithm behind the scenes in pseudocoded comments. I typically end with a NotImplemented exception as we all know that we haven't finished implementation yet.
Talking Through a Code ReviewWhen I review code, it helps that the variables used make sense and that the algorithm is clear and concise. The code itself becomes self-documenting. In the case that it isn't, comments come to the rescue. When sitting with one of my developers, I'll first make one pass stating what I believe it is doing. The developer corrects me if I'm wrong, and once we agree on its algorithm we document each line. One should be able to rip out all the code, leave the comments, and still be able to rewrite it based on the algorithm as described by the new comments. With a fresh set of comments in-line, we then verify the correctness of the algorithm. The unit tests updated and the world is good!