Hacker News Reader

Comment by temporallobe | Hacker News Reader

I’ve been about 6 months in Clojure, and I am finally starting to like it. Coming from decidedly non-Lisp languages, it’s been a struggle. For example, immutability is possible, but not natural to most other languages; for Clojure, it’s instrinsic. I also often scratch my head at the way things ate scoped and tbe whole concept of purely functional programming. Clojure is very powerful and terse, but what I dislike the most, just like with Ruby, is the culture that the code should be self-documenting and self-explanatory. In all the code I have been maintaining this whole time, comments are rare, whereas in Java, C/C++, JS, etc., comments are plentiful and encouraged. I feel like with Clojure, I am expected to understand the code just by reading it. What gives?

View on HN

Consider comment inflation.

Comments should only be needed when things are especially complex and if they are everywhere their average value goes down. Most codebases of good quality that I've seen have not had particularly detailed comments--except where you really need them. The mere existence of a comment already hints that the code that follows needs to be carefully understood before you can touch it!

There might be boilerplate comments before each function to describe the function and explain the parameters but other than that comments are only reserved for the tricky interactions. But in many cases also this information can be embedded in the name of the function and its parameters!

Good code reads well because it's built on top of lower level blocks that are simple and well-defined. And those are simple and well-defined probably because they are also built on top of even simpler things. This removes the need for a lot of mundane comments.

I don't think Clojure is more exceptional with regard to this than other languages. But I think a higher percentage of Clojure code is of good quality, and that probably is because Clojure attracts good programmers who care about these things.

Most of the time, a comment can be substituted for a well-named function.

As a trivial example, something like:

    (int (* 1000 seconds))  ;; seconds -> milliseconds

Can be replaced with:

    (seconds->milliseconds seconds)

Without loss of clarity.

Ideally, comments should mostly be used to explain 'why' rather than 'what'.

> I feel like with Clojure, I am expected to understand the code just by reading it.

Yes, you are. Outside of example code, this seems reasonable to me. If you can't understand the code just by reading it and a short docstring, it's a sign the code is too complex. There are cases where such complexity can't be helped, but they're not common.

I don't really find that the community is against documenting code, and majority of popular libraries have doc strings for the public functions at least. In general, I do find that reading through decently written Clojure code tends to be easier than languages like Java or Js. The code tends to be a lot more declarative, there are a lot less syntax quirks, and functions are typically kept short. Meanwhile, majority of the code is written using pure functions, so you can figure out what they do without needing a lot of context about the rest of the program. I also tend to just run things in the REPL any time I'm not sure what a piece of code might be doing. So, while I'm definitely a proponent of having good documentation, I find that I have a much easier time reading through Clojure code than most languages I've used.

A lot of people agree that while Clojure has a lot of powerful things going for it, documentation is not one of them, eg: https://www.youtube.com/watch?v=1YCkOo5Y4Oo

It's definitely overwhelming in the beginning but after a while docstrigs + reading code seems to hit a very good tradeoff for me. And just using comments for weird or unexpected behaviour.

There are alos efforts to put more focus on documentation though: https://cljdoc.xyz/

Reply on news.ycombinator.com