Re: coding style rules

Sasa wrote:
Hi,
Hopefully this is the appropriate group. I was wandering what are your thoughts/opinions about following rules:


1. Each class should reside in its own file (or .h/.cpp pair in C++ case)

In my opinion this rule is too strict. While it makes sense most of the time, I find that sometimes couple of small classes which logically "belong" together should be put together in a single file (or pair). One example would be the case when one small class is devised to provide services for only one class (i.e. some part of behavior of one class is extracted to new class simply to make the original class more readable and maintainable).

Consider also the flip side: a single class spanning multiple files because of its own logical divisions. To borrow an example from C++, the bool specialization for std::vector will "override" (specialize) almost every method of the vector class because it has a unique implementation. It therefore makes sense to me to put the bool specialization of std::vector in its own file; thus one class (std::vector) spans multiple files. (And indeed, that is what g++ does.)



2. Each class/function should have header comment so that documentation can be automatically generated.

Again, I find this to be too rigid. Personally I like to break down implementation in a lot of small classes and methods and use intention revealing names to communicate their purpose. While I find that automatically generated document has indisputable advantages, I think it's too much to insist that absolutely each segment of the implementation should be thoroughly documented. Lot of those small classes and/or methods are low level implementation details, and are, if well designed/written, comprehendable merely by inspecting the code.


Any opinions/suggestions/references would be very appreciated.

A risk with comments is that they tend to get out of date as the code changes, especially with header/implementation divides like you find in C++.

-Peter


--
Pull out a splinter to reply.
.

Relevant Pages

  • Re: TiddlyWikis for world building
    ... I was doing some documentation for work the ... as it's perfect for managing lots of scrappy notes in a single file, ... rather than a mass of files in a folder. ... Kay Shapero ...
    (rec.arts.sf.composition)
  • Re: two file into a single file
    ... You will need to use the openbuiltin for each input file, and again for the output file. ... Documentation is available in the python tutorial here: ... two file into a single file ...
    (comp.lang.python)
  • Re: How to create a single executable of a Python program
    ... documentation, shortcuts etc.. ... I just want a single file to run! ... Gabriel Genellina ...
    (comp.lang.python)