Hacker News Reader

Comment by kd0amg | Hacker News Reader

While reading someone else's program that uses a DSL may be superficially easy, but the minute you try to get under the surface, you're left scrambling to understand what a given term or idea meant to the author. There is no language definition to rely on for common understanding.

I have generally found that this is the same problem as with user-defined functions, and it has the same solution: programmers need to document their code.

View on HN

Agreed. I have two follow up thoughts:

1. Badly designed functions can do less design damage per-function than badly designed languages per construct, but user-defined functions tend to have much higher volume than both language constructs and their usages.

2. Powerful techniques, including DSLs, lead to denser code. Denser code takes more time to read per unit of code. Total reading time may be either more or less, but the cold start ramp is always much steeper.

Combined, this means that people are less sensitive to suffering the complexity caused by user-defined functions vs DSLs/etc because that complexity has lower intensity spread out over a greater area. I'll refrain from any further value judgement on this state of affairs; just wanted to share some more insights in to the tradeoffs.

> Badly designed functions can do less design damage per-function than badly designed languages per construct

Really? When was the last time you successfully used a C library without reading the documentation?

Straw man. When was the last time you had to check the documentation for the parameter evaluation strategy of a C function call?

I don't think it is a controversial statement than a badly designed macro can do more damage than a badly designed function. I believe that this is true, even normalizing for bad macro systems. This is not a statement against macros, so much as it is a statement to consider when making tradeoffs.

It is controversial. The GETS function is probably responsible for a huge number of security breaches with a cost possibly ranging into the billions of dollars (there's no way to really know). What would you cite as a comparable example of a badly designed macro?

Part of the reason gets() has been such a disaster is that people use it.

What would you cite as an example of a badly designed macro?

If you need documentation probably you are not writing good code. Documentation is absolutely needed when writing third party libraries, but everyone of your team should know all the aspects of the codebase, at least at high level. If someone doesn't know it then documentation is not the solution. Doing some pair-programming, adding them as reviewers of more pull requests, writing some wiki page that explains the architecture of the various components are much more effective ways. Remember that documentation is not free, you need to spend a certain amount of time to build it and even a greater amount of time to maintain it. Every time that I've seen some attempt at writing documentation in javadoc or whatever is called in .net, there were always missing parameters in the methods, wrong arguments and method names, parameters not existing anymore and so on. Naming is also a very important aspect. Just yesterday I found in a pull request something like "SingleLineTextBoxTextTooLongShowTooltipHandler". This doesn't really add any information and just makes it impossible to understand what is meant to do. I proposed to change it to "TextOveflowTooltipHandler", maybe still not ideal, but I think that is a definite improvement over the original.

DSLs in theory should be self documenting. Gherkin is quite easy even if you don't read the documentation and even if you don't write code. If on the other end you write some Lisp-esque ultra compact DSL that has no whatsoever connection with the real world then also in that case the best solution is not to write the documentation, it should be to write a better DSL.

> Doing some pair-programming, adding them as reviewers of more pull requests, writing some wiki page that explains the architecture of the various components are much more effective ways

You get a new member of the team, how do pull-request reviews and pair-programming help them get familiar with old code? Documentation is a way of stating explicitly what might be learned implicitly from those tasks.

> Every time that I've seen some attempt at writing documentation in javadoc or whatever is called in .net, there were always missing parameters in the methods, wrong arguments and method names, parameters not existing anymore and so on

So fix that. review the comments as part of code review - if the documentation is in the code this should be easy. From my memory of Java, doesn't eclipse have some sort of doc sting checker? I'm sure I recall the in-comment parameter names changing when you updated the method name...

That's one thing that I liked with FP often combinatorics friendly code, you can compose lots out of a common core, it helps tremendously to decrypt the author's idea.

Also be consistent with their grammar, naming schemes, and conventions.

Reply on news.ycombinator.com