Hacker News Reader

Comment by nickpeterson | Hacker News Reader

One thing I really liked about the DDD idea of ubiquitous language was that you reduce the amount of artificial abstractions between domain experts and the code, and it forces developers to be able to converse better with the business. I also think we should be doing a much better job documenting the intent of an entire system. New features get added by working them into the narrative of the 'Document of Intent', rather than becoming some set of requirements in an issue tracker. Otherwise we have difficulty understanding 'why' a system works the way it does, and possibly, if that way is actually incorrect. Many companies I've worked at, the system 'becomes' the rule. Even domain experts will ask what the system currently does when pressed for how something should happen. I think at a certain scale, it's just hard to keep business process in a single person's head.

View on HN

Something I've considered on and off is that our current way of writing code is insufficient, I'd really like to have an editor/IDE that had "layers" so that I could attach code related comments in one layer and intent/documentation in another layer - throw in the ability to hide/show layers at will and you'd have a much more flexible way of documenting code than we currently have.

It was possible do it with literate programming for ages. Combine it with emacs, mmm-mode and, say, auctex - and you'll get your IDE.

I used litcoffee* for a while, and it really makes you think about and code for a future reader / maintainer, which is pretty great.

It really slows you down though (good thing?) when trying to dump your ideas into code, especially if you end up writing exploratory code that you later delete (I do this a lot).

I think literate code could be really great however for refactors. Once you've figured out the correct implementation and have the time & hopefully budget to revisit your fast code. Maybe it won't feel like the chore of straight up documentation, and more like the enjoyment of polishing your art.

* http://coffeescript.org/#literate

Interesting. My experience is different - I write my throwaway code starting with a free form prose, dumping all my vague ideas into a text, which is then filled with a very volatile code to explore the listed ideas. It results in a mess, of course, but a mess with a track of what I tried to achieve.

I'd always rewrite what is left of such an effort from scratch, but it is easy to do so with all the literate brain-dump surrounding my code.

Definitely a different approach. I think I will try that. I would imagine you end up refactoring the documentation as much as the code.

I pair quite a bit these days, and this may compliment our process nicely.

You could probably hack this into an editor with folding support, such as Vim. Just tag each layer with a different folding marker, and bind a hotkey to open/close all folds for that layer.

http://vim.wikia.com/wiki/Folding

I do worry about programmers forgetting to check hidden layers even more than we may currently tend to ignore comments, so I worry about this adding parallel maintenance burdens even worse than the common problem of comments getting out of date with the code. Maybe there could be some way to have compile-time diagnostics or static tools to enforce updating of the documentation layers with the code. Though that could add obstacles to adoption, as the tools and meta-concepts would have to evolve along with the layering concept itself.

IMO that's sort of what some forms of testing are designed to accomplish, in a way which is a little less-prone to unattended divergence or rot.

Augh! Stop reading my mind! I've been working to push DDD-ness on my company for a couple years now, and it's been tough.

A contributing factor is organizational: There can be a managerial or "coordinator" layer composed of people who have neither the domain-knowledge of end-users nor the technical-knowledge of programmers.

Unless this layer is composed of very good people, what you get are specs that resemble a game of "telephone": Even if they're detailed with mockups etc, what the specs actually encode is what Alice thinks she needs to ask for in order to satisfy the request of Bob which is based on him thinking about what design might solve his problem, etc.

In my experience some small rules can help to grow towards DDD. For example when the team starts to use immutable model objects everybody is forced to think in a more domain driven way because what happens at the model constuction becomes very important.

We have a clear vocabulary problem especially in the UI layer, where we never really know what to call things. I've been working on a test tool that involves assigning a natural language name to each rendered entity, so you can then tell the tool to "Look at the sidebar. Click the compose button. Now look at the profile pane. See a message composition view." The hope is to get both a test suite and an encouragement to think of the UI entities in a more "ubiquitous language" type way. It's still an early experiment but it's turning out quite nicely and I hope to release it as open source within a couple of weeks.

Yeah, I've been pushing them to use a lot more immutability / "versioning" of items. Have a mutable copy used for composing purposes, and spawn snapshots from that which are what the rest of the system uses.

The actual way the data is used isn't particularly high-performance or massively-parallel, so it's all about fencing-in crappy logic and avoiding zillion-phase commits.

I recently thought that there should be 10-times rule for good documentation. So, every line would be documented (best if self-documented), every 10 lines (which is roughly a function), every 100 lines (a class?), every 1000 lines (a module), and so on until you got to the top of the system. But it's an awful lot of documentation to maintain.

Reply on news.ycombinator.com