>>>>>>HI All,
>>>>>>
>>>>>>This has been a pet-peeve of mine for some time. A long long time ago, when disk space was sparse, comments in code was frowned on. Too many comments would bring sever finger shaking at me. "We can not afford wasting disk space!" OK. That was then, this is now, with terabytes of disk space, why not take the time and place a comments as to what the code is intended to do? I still see new code with very little to no comments to help me follow the purpose of the code. Not to mention (ok, i will), planning the flow of the code ahead of coding.
>>>>>>
>>>>>>Why is this? Should I be striping the comments out before sharing it with others, and to help confuse myself years later when I revisit the code for maintenance?
>>>>>>
>>>>>>Only looking for comments on the subject. ;)
>>>>>
>>>>>https://www.codeproject.com/Articles/872073/Code-Comments-are-Lies
>>>>
>>>>
>>>>I use comments to pseudo-code a routine before actually writing the code. This generally results in the comments becoming description to a block of related code. Other times I comment a complex equation to emphasize its' purpose. Then sometimes I just add comments so I can remember why I did the coding the way I did. And then with complex SQL statements it is easier to place a comment that describes the intent of the statement then it is to spend time deciphering the lengthy SELECT statement. But in most cases, I fined over commenting less troublesome then the lack of comments when trying to interrupt other peoples code. I try to code for the future maintenance or enhancements.
>>>>
>>>I am a strong believer of Als link - code should speak for itself. If it doesn't, variables, functions and methods are not named well enough.
>>>Parameters and returns should be described to allow usage without reading the method code.
>>>
>>>But apart from that, there are few things to comment: whenever there was a need to code against project best practices (often performance tweaks) and a list of approaches tried, but NOT taken or abandoned, best with a pointer to source control where it was active. Also ideas not tried yet (often also performance)
>>
>>I agree with the concept that "code should speak for itself". In the case of FoxPro, this is easy. But there are several development languages where this philosophy is difficult to apply.
>>
>>I have been directed to a project (recently) to implement a menu system written in C#. The demo ran great. But the code was based on pointers to pointers to objects with short obtuse names. There was no documentation or comments to aid me into understanding how the code worked. After wasting a few days trying to interrupt the code, I gave up. I am sure that it made perfect sense to the developer. But to me, not being the Advance Guru in C#, it was difficult to follow. Had the many (hundreds) of routines and classes been at least comment a little as to their purpose, I may have been able to implement it. But I felt I was work with a mobile with many rods and weights. Each attempt to work with it would result in the entire structure becoming unbalanced and failing. To bad. It has many desire features. At one point, I change a bitmap (same format and size), and the entire demo fell apart. If there had been at least some indication as to the limitations, perhaps I could have used it.
>>
>>But enough ranting. My pet-peeve is not that comments are necessary, but aid in helping others to understand the direction of the coders' intent. So that people like myself can use their tools without having to strain in reading and implementing it.
>
>Good point. But what I usually miss even more is the general overview of a project design. I guess that is because of time contraints (like manuals often face the same fate), and the question how to do it so it is really useful. A graphical overview would be great, but projects are generally too large to be able to fit into a picture. A Word document is difficult to structure in a way that you could find what to look for. But it would be great to be able to view the project in macro style, and then drill down into modules, viewing all related classes and then drill into micro style and see the properties and dependencies. I never came to the point to be able to envision how that could be accomplished.

I totally agree with you. Maintaining a Word document is not only tedious, but generally incomplete and complicated to follow. Using a web-style documentation adds different levels of dimensions to the documentation. Allowing the drill-down and feature groupings. Also, if the web document is on-line, it is easier to maintain and distribute. IMO.