Out of politeness, I queried whether it would be ok to ask the problem, but I received no encouragement to do so. That's fine, as the thread is OT. So, I'm sorry that you're irritated, but ...
That was explained in the OP, actually.
Ah, at last an answer to the question many of us were too reticent to ask ourselves!
I learnt my comment style writing Assembler
;*********************************** ; This subroutine validates and cleans ; up user alphanumeric input by returning ; either the valid upper case character, or a zero ' AX register ised to pass the character ;*************************************************
CMP AX '0' JL BADEXIT ; if character is less than ascii zero, bin it CMP AX, 'z' ; if character is less than ascii 'z, bin it JG BADEXIT ; character lies between 0 and z... CMP AX, '9' ; 0-9 JLE GOODEXIT ..... and so on
BADEXIT: MOV AX,0 GOODEXIT: RET
The point being a random collection of assembler isn't immediately obvious, so a header block is used to explains what it is supposed to do. In a big project this might form part of a documented library of subroutines.
Most code in the public domain is extremely badly documented, to the point where its hard to see what is actually intended.
Programmers think this makes them look smart
(Java JIve is a programmer).
But for what purpose? Experience, for me, suggests Javadoc style documentation is frequently bordering on useless.
Good support for an api is: exemplar code samples, regression type tests, unit tests, and access to source code.
No such thing as a stupid question.
ROFL. I've had to support too much 'professionally written' code like that during my 35 years in that business. Without decent comments, documentation, or department *standards*, even COBOL can become tediously difficult to maintain
We went to an agricultural college !!!
It is stupid to ask if the sun will come up again tomorrow.
It is stupid to ask if you can get to the moon or the other side of the earth by eating lots of beans.
It is stupid to ask if Boris will still be PM at Xmas.
It is stupid to ask if you are a dick, the answer is obvious.
HomeOwnersHub website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.