News for hackers. Stuff that matters.
Re:It's not what programming languages do, it's what they sh... by mickduprez on Friday March 27, 2020 @06:27AM (#22701679)
That's a shame, you hear this a lot about lisp code and I think the problem is that the people who really grok lisp and write 'genius' code can be a bit blase about documenting their code.

Simple documentation for standard function definitions is fine but macros definitely need special attention. Some say macros are over-used but I think it's more of a case they're under-documented. Even if the name of the macro gives you a fair idea, documenting how it works and what is generates with examples goes a long way to deciphering them for maintenance. cheers.

Re:It's not what programming languages do, it's what they sh... by pdimitar on Friday March 27, 2020 @06:31AM (#22701698)
Absolutely. In fact I am writing a library in Elixir currently (for internal company usage) that mandates generating boilerplate to help a user project. It's a really fine balance to (a) not being too clever by making the macro code still readable and (b) documenting the intent of the macro, its input and output, and why it is actually useful.

Many people are like "I'll document it later" and it just almost never happens. Which is, as you said, a shame.