Self-Documenting Code

Pages: 12

Simple adapter does not stop someone from doing memory magic can getting the wrapped object.

It protects from those who will search for underlying type definition to check what it can do and using its methods. Making your code foolproof can save you from long refactoring or even reverting some files or from searching for some elusive bugs.

LB (13399)

I guess I'm trying to use type aliases as if they were a language feature that limited the available interface of a class. Oh well.

closed account (3hM2Nwbp)

Implementation code and documentation don't mix well from my experience.

If an implementation needs to be documented (or worse yet -- requires a user to read its source code to figure out what it does), then the implementation is faulty.

An interface, on the other hand is where documentation belongs. If any ambiguity exists in the interface documentation, then either the documentation or the interface itself is faulty.

That system has always worked well for me.

* Example:

Interface
https://bitbucket.org/DarkHeart/midnight-engine/src/fac6468359d695587e970c87063b5d0f071d3726/Matrix.hpp?at=master

Implementation
https://bitbucket.org/DarkHeart/midnight-engine/src/fac6468359d695587e970c87063b5d0f071d3726/Matrix.inl?at=master

Documentation (albeit a bit out of sync -- need to regenerate)
http://midnightengine.com/api/classmidnight_1_1_matrix.html

Last edited on

BHX (3450)

@LB
So you don't like the C library. Don't care for and refuse to use PHP. Are struggling understanding languages with weak/dynamic typing (Python/Javascript per your example). So is there a language besides C++ that you like?

Last edited on

LB (13399)

Java's OK, besides the garbage collection. Unfortunately I don't really have the time I'd like to be able to get familiar with other languages and possibly like them.

Last edited on

BHX (3450)

That is a shame. Sorry, didn't mean to derail your thread, but I was curious after our discussion on PHP, your C comment here, and the other recent thread.

xander333 (641)

@LB you can use the new <article> tag from HTML5 and give it a fixed width (ie 750px) very easily with css!

article {
    position: relative;
    width: 750px;
}

MiiNiPaa (8886)

On topic: I wish C++ had strong type aliases. Something like

using explicit byte = char;
char tolower(char);
void send(byte);
//...
char c = 'a';
byte b = 0xEA;
tolower(c); //OK
send(b); //OK
tolower(b); //ERROR
send(c); //ERROR
send(static_cast<byte>(c));//OK, explicit conversion

It helps against those who might violate type safety (try to use underlying type instead of alias, or pass alias to function expecting underlying type) and helps to hide implementation details.

LB (13399)

Yes, I'd like strong type aliases too. At least we got enum classes.

Topic archived. No new replies allowed.

Pages: 12