self-documenting

Documenting class attribute

Following sample is taken from "Dive into python" book. class MP3FileInfo(FileInfo): "store ID3v1.0 MP3 tags" tagDataMap = ... This sample shows documenting the MP3FileInfo, but how can I add help to MP3FileInfo. tagDataMap ...

Should programmers use boolean variables to "document" their code?

I'm reading McConell's Code Complete, and he discusses using boolean variables to document your code. For example, instead of: if((elementIndex < 0) || (MAX_ELEMENTS < elementIndex) || (elementIndex == lastElementIndex)){ ... } He suggests: finished = ((elementIndex < 0) || (MAX_ELEMENTS < elementIndex)); repeatedEntry = (...