After Hours

General discussion


You're Missing the Point

By dogknees ·
Tags: Off Topic
article root

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Comments

Collapse -

Still Missing the Point

by dogknees In reply to You're Missing the Point

This whole discussion is specifically about the sort of comments generated automatically by the type of tool being discussed here. My comments are directed explicitly to these comments and do not refer to programmer created and maintained comments.

Having clarified that, my point is that these (automatically generated) comments do not add any information that is not in the method signatures. Comments that are less succinct than the code are not only useless, but are actually make reading the code harder.

Of course comments about how the code works and what it achieves are required. But, Auto-comment-generators don't assist with these. If you look at a lot of Java library docs, you see the same issue. All they do, without direct input from the programmer, is repeat the names and parameters of the public member functions and objects in a class. This is completely useless without detailed information that explains what each does and how they interact to provide useful functionality.

When I look at library documentation I want to see the how and what. Detailed, complete documentation of the classes involved. Every option listed and defined. Every public piece of data listed and explained. Not "iLevel is an integer", but "iLevel represents ..... When iLevel has values less than 1, ..... It changes when the following member function is called....."

I've spent over 20 years working on various size projects, and spend a lot of my time de-constructing systems written by others so I can access their date or extend/modify their functionality or interface. My experience is that the dumb lists of functions, parameters, locals and the like do not make it easier to familiarise myself with the code.

Related Discussions

Related Forums