I graduated in 1990 in Electrical Engineering and since then I have been in university, doing research in the field of DSP. To me programming is more a tool than a job.
My usual approach is to put comments in the spec file of a package to document the API of the package. If what a procedure/function does is quite obvious from the function and parameter names, maybe the comment reduces itself to one or two lines, just for the sake of automatic documentation extractors.
It is really unusual that I put comments in the body part, only if I am using some complex and counter-intuitive algorithms. Often I prefer to comment about the code status in a point by using "executable decorator" such as Assert, Loop_Invariant and contracts.
Sometimes I put a long (sometimes very long) comment at the beginning of the file where I explain what that specific package does and what is the "abstract model" behind it, abstract model that is somehow independent not only on the implementation details, but also on the API details.
An example: you have a package that implements the usual Employee class. In the context of your application an Employee can have a name, a serial number, a base monthly cost and it can be in several states (On_Vacation, At_Work, Ill, Goofing_Off, ...). Note that this model is independent on the API details (how are we going to change the cost? With a method Set_Salary? Or will it be a Apply_Increase?).
In my experience, having a conceptual model of what that package is trying to do helps a lot in understanding its API.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
My usual approach is to put comments in the spec file of a package to document the API of the package. If what a procedure/function does is quite obvious from the function and parameter names, maybe the comment reduces itself to one or two lines, just for the sake of automatic documentation extractors.
It is really unusual that I put comments in the body part, only if I am using some complex and counter-intuitive algorithms. Often I prefer to comment about the code status in a point by using "executable decorator" such as Assert, Loop_Invariant and contracts.
Sometimes I put a long (sometimes very long) comment at the beginning of the file where I explain what that specific package does and what is the "abstract model" behind it, abstract model that is somehow independent not only on the implementation details, but also on the API details.
An example: you have a package that implements the usual Employee class. In the context of your application an Employee can have a name, a serial number, a base monthly cost and it can be in several states (On_Vacation, At_Work, Ill, Goofing_Off, ...). Note that this model is independent on the API details (how are we going to change the cost? With a method Set_Salary? Or will it be a Apply_Increase?).
In my experience, having a conceptual model of what that package is trying to do helps a lot in understanding its API.