On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:
On 29 March 2012 13:58, Nathan M. Swan <nathanms...@gmail.com>
wrote:
On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
Categories - worst idea ever.
What's better:
int a; // this is size
OR
int size;
Same thing applies here - code MUST be self documenting as
much as
possible.
But categories are still useful, e.g., when you want a
function in
std.algorithm that looks for a specific element. It could be
"search" or
"find" or "firstElemSatisfyingCondition", and even though
those are all self
documenting, it would be a pain to look through the list of
functions in
alphabetical order. The use of categories narrows your search
for the
function down 20%.
NMS
Exactly my point. There is a line between "code must be self
documenting" and "I need to read the code to understand what
this
does". Self documenting code is more about removing the
cognitive
stress of reading code. Actual documentation needs the whys and
wherefores about everything.
std.string is a brilliant example, with a list of 68 functions
at the
top, and a total of 89 anchors (presumably just overloads),
there is
no easy way to quickly find a function for a purpose. You have
indexOf
- a searching function - next to insert - a manipulation
function -
next to isNumeric - a property testing function. Each of those
functions are "self-documenting" but that doesn't mean they
wouldn't
benefit from categorization.
--
James Miller
Have you considered that perhaps the granularity of Phobos
modules is too coarse? Perhaps the core issue is too many
functions are placed in one single file without more
consideration of their relation and organization?
Regarding the documentation system itself - it should provide as
much automation as possible. For instance, it should be able to
group overloads together, it should be able to group kinds
together - types, free functions, enums, etc. it should be able
to group together various parts of a compound type (by
protection, by kind: constructors, properties, operators, etc. )
Given the above *and* proper organization of code - which is
*not* the case today - an *optional* tagging system could add
some small benefit if it's automatic. E.g add a TAG macro.
Relying on documentation before exhausting the above is IMHO
wrong.
As others said, the documentation and code comments should
reflect what the code itself cannot express - what is the higher
goal we want to achieve, which specific implementation tradeoffs
were taken and why, etc.
breaking algorithm.d into manually maintained documentation
"categories" clearly misses the above points.
