Questions tagged [self-documenting]
6 questions
79
votes
14 answers
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…
froadie
- 79,995
- 75
- 166
- 235
5
votes
3 answers
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
Dewfy
- 23,277
- 13
- 73
- 121
2
votes
0 answers
Most portable way to embed a README message in an RData (R workspace) file
I'm developing a workflow where user-submitted data are validated and some preliminary statistical tests are run, and then the resulting workspace is sent to a statistician for further analysis.
In some scenarios, the RData file will be sent to a…
bokov
- 3,444
- 2
- 31
- 49
0
votes
2 answers
documenting a library -- everything or just the functions from the public header?
if you are developing and documenting a library.. do you document every single function / data structure from every source file, or just the public ones that appear on the public header??
im leaning to the second option, is this ok?
labotsirc
- 722
- 7
- 21
0
votes
1 answer
GraphQL is not self documenting
I've created a GraphQL API for a project I'm working on using webonyx/graphql-php. I'm using Altair Chrome Plugin to test it. The API itself works fine, I can get the data without a problem, however Altair does not display any kind of documentation…
Sorcy
- 2,587
- 5
- 26
- 34
0
votes
2 answers
In SQL Server, what does it mean to be self-documenting?
I came across this term in a reading. Here is the context:
"It is a best practice to make your T-SQL code self-documenting. Generally speaking, a view
will be more self-documenting if the column names of the view are specified in the SELECT
…
Mitchell Walker
- 211
- 3
- 8
- 18