4 ms·

This can be a double-edged sword when it comes to coding, as code and documentation can very easily fall out of sync. I am in favour of trying to write self-doc

This can be a double-edged sword when it comes to coding, as code and documentation can very easily fall out of sync. I am in favour of trying to write self-documenting code, with clear unit and variable names, with an automated system to convert that to a human-readable format. Any separate documentation should focus on more areas that are not easily concluded from the code -- like intent, architecture and the like.

noir_lord 8y ago
Documentation of code tooling is terrible. I still don't know why we haven't stolen the Photoshop layers paradigm and applied it to code I should be able to toggle a shallow layer and deep layer all from a single 'file' So the you'd be able to have architectural notes in the deep layer etc. In many ways our tools are stuck in time.
- organsnyder 8y ago
  Fascinating idea. Though from my experience with a crude approximation of part of it—Javadoc (or the equivalent) that's folded by the IDE—keeping the deeper layers up-to-date would be an uphill battle at most organizations.
- oofoe 8y ago
  Actually, the old Forth block editors did this with their screens and shadow-screens. The normal unit of editing work in original Forth was a 1024 byte "page" called a SCREEN. You would write your code in an editor that arranged it as 16 lines of 64 characters. At the touch of a key (usually), you could swap to the shadow screen which would have the documentation on it. By convention, shadow screen comments were placed on the same line as the code they were remarking on, so everything was usually co-located. By abusing autorepeat, it was even possible to "flicker" the code and documentation to see both at once. Something like CWEB or org-mode permits interleaving code with comments, but it's one dimensional and breaks your flow when editing.
  - noir_lord 8y ago
    That's why it'd have to be layers and you'd have to have some clever way of keeping what in each layer goes with which code. I started playing with it a while back in terms of how you'd structure it and what I came up with was something like foo.cs foo.shallow foo.deep So that all existing tooling would work, foo.cs would just be regular old code and only if your editor supported layers would it care about .shallow and .deep, I didn't like that it would clutter up files. If I ever get the time I'd like to implement a rough prototype in intellij.
yonaguska 8y ago
I like this, in addition, I believe in documentation through unit tests. Especially when dealing with edge case business logic. Implement a test that has a verbose name or description testing that logic. If someone breaks it- they are notified through a failing unit test, then they also have a clear reference of why the logic was there in the first place and they know that now they have to go to product to figure out if the logic is still relevant.
wool_gather 8y ago
I think that "self-documenting code" only covers the what, though. Code, regardless of style or language is fundamentally just a bunch of instructions; the why (and sometimes how, i.e. assumptions/preconditions/platform-level details, and so on) can't really be encoded there.
ravenstine 8y ago
> I am in favour of trying to write self-documenting code, with clear unit and variable names, with an automated system to convert that to a human-readable format. That's great and all, and I agree in principle, except time and time again I've witnessed people use the "my code is self-documenting" thing as an excuse not to describe anything they've written in plain English. Much of the time, it's pure arrogance of developers who think their shit doesn't stink. I'm not expecting people to litter their code with comments explaining what every line is doing. On the other hand, a project that can't even run on a dev's machine without having to repeatedly ask someone questions is unacceptable, and core architecture and concepts should be summarized so that new developers won't eff up or rethink ideas that have already been thought out.

noir_lord 8y ago

Documentation of code tooling is terrible. I still don't know why we haven't stolen the Photoshop layers paradigm and applied it to code I should be able to toggle a shallow layer and deep layer all from a single 'file' So the you'd be able to have architectural notes in the deep layer etc. In many ways our tools are stuck in time.

organsnyder 8y ago
Fascinating idea. Though from my experience with a crude approximation of part of it—Javadoc (or the equivalent) that's folded by the IDE—keeping the deeper layers up-to-date would be an uphill battle at most organizations.
oofoe 8y ago
Actually, the old Forth block editors did this with their screens and shadow-screens. The normal unit of editing work in original Forth was a 1024 byte "page" called a SCREEN. You would write your code in an editor that arranged it as 16 lines of 64 characters. At the touch of a key (usually), you could swap to the shadow screen which would have the documentation on it. By convention, shadow screen comments were placed on the same line as the code they were remarking on, so everything was usually co-located. By abusing autorepeat, it was even possible to "flicker" the code and documentation to see both at once. Something like CWEB or org-mode permits interleaving code with comments, but it's one dimensional and breaks your flow when editing.
- noir_lord 8y ago
  That's why it'd have to be layers and you'd have to have some clever way of keeping what in each layer goes with which code. I started playing with it a while back in terms of how you'd structure it and what I came up with was something like foo.cs foo.shallow foo.deep So that all existing tooling would work, foo.cs would just be regular old code and only if your editor supported layers would it care about .shallow and .deep, I didn't like that it would clutter up files. If I ever get the time I'd like to implement a rough prototype in intellij.

yonaguska 8y ago

I like this, in addition, I believe in documentation through unit tests. Especially when dealing with edge case business logic. Implement a test that has a verbose name or description testing that logic. If someone breaks it- they are notified through a failing unit test, then they also have a clear reference of why the logic was there in the first place and they know that now they have to go to product to figure out if the logic is still relevant.

wool_gather 8y ago

I think that "self-documenting code" only covers the what, though. Code, regardless of style or language is fundamentally just a bunch of instructions; the why (and sometimes how, i.e. assumptions/preconditions/platform-level details, and so on) can't really be encoded there.

ravenstine 8y ago

> I am in favour of trying to write self-documenting code, with clear unit and variable names, with an automated system to convert that to a human-readable format. That's great and all, and I agree in principle, except time and time again I've witnessed people use the "my code is self-documenting" thing as an excuse not to describe anything they've written in plain English. Much of the time, it's pure arrogance of developers who think their shit doesn't stink. I'm not expecting people to litter their code with comments explaining what every line is doing. On the other hand, a project that can't even run on a dev's machine without having to repeatedly ask someone questions is unacceptable, and core architecture and concepts should be summarized so that new developers won't eff up or rethink ideas that have already been thought out.