Clojurians Log v2

They seem to have a lot of things to curse at 😅

Have you actually seen/worked on extensive documentation that tries to enforce having one sentence per line? If so, how did it go? Would you generally be in favor of or against it? source: https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

i think the idea is slightly different from your description

> By starting a new line at the end of each sentence, and splitting sentences themselves at natural breaks between clauses

I wrote my master's thesis in LaTeX, and chose to have one line per sentence. Git commits became more specific, and that alone made it worth it. These days, I don't think I'd bother.

Oh that's right, thanks. I missed the second part. That's even more extreme than what I had in mind... Regardless, I think that the principle is quite similar in both cases.

Btw that's only the case in the semantic linefeeds approach, the rest don't seem to split up sentences

Diffs look much better, that's right. I also think it kind of promotes writing shorter sentences but that's just a hunch. :thinking_face:

have tried it, and found it to be really hard and invasive to remember to do, and in the end, not worth the effort

'one sentence per line' sounds painful to follow but I'm not a fan of word-wrap at a fixed column count either. When reading the source code (particularly in docstrings) it can read unnaturally, because the newline was placed in whatever position column N was Sentences are organised in phrases, placing a newline after each phrase if needed tends to be naturally readable (I think some literature follows this style?)

I’m trying it out in for rewrite-clj docs and like it.

People who hate PHP tend not to actually use it

Would be quite hard using Groff ;)

Referring to previous topic ^

I did not realize/remember that https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/.

well, that's not necessarily a coincidence.

(<-- EX-PHP programmer)

In spite of all of PHP's quirks, there were a bunch of reasons why PHP became popular. We take for granted the incremental development workflows available today, but PHP has had incremental workflows as the default for a long time and without any complicated tooling (just save and refresh). For simple websites, state management for PHP was also pretty good. All state was stored in a relational database and html pages were generally derived from that state using pure functions. Deployment for php was also incredibly easy, just copy your project to the webserver. It's not to say that PHP exemplifies the epitome of software development, but I think it does show how straightforward tooling and a functional approach to state management can allow people to start building useful software without a steep learning curve. I think some of the negative press PHP has received is sort of a simpson's paradox. PHP is a lot easier to get started with and there's a lot more useful code that's written by inexperienced programmers. There's a lot less useful code in other languages written by people with similar levels of experience.

CFML (ColdFusion) suffers from that same paradox: very easy to get started with, lots of functionality out of the box, so a lot of “non-programmers” were able to build quite complex web projects with it — and produced unmaintainable codebases along the way, giving CFML an even worse rep.

To be fair, I think a lot of my own personal prejudice against PHP stems from people trying to invent Rails for PHP, which just drove me nuts.

PHP itself isn't really as terrible as curmudgeon-me likes to claim.

CFML has cfWheels — which is quite literally a Rails clone (but the framework’s codebase is horrendous).

that too. there were people who tried to Java-ize PHP which made things worse IMO

Oh yeah, big time.

If the framework's codebase is ugly, then it's a better "clone" that I initially though :rolling_on_the_floor_laughing:

Is it considered a common practice on Clojure to use markdown on docstrings? Or is the idea quite silly? I know that core functions don't do that, but I'm curious if someone else does it...

http://cljdoc.org supports it so I think more and more people are using MD in docstrings these days (I think several auto-doc projects support it — but http://cljdoc.org is the most common now I think).

(so I’m using MD on nearly all my docstrings in my OSS projects now)

The ‘victim of success’ pattern seems to come up a lot in programming. Lots of people using it = lots of crap written in it and about it.

I use markdown in some docstrings for rewrite-clj, code blocks can sometimes be hard to edit, but looks real nice on cldjoc.

Yeah, although CFML isn’t exactly something I’d consider “successful” — it certainly had a very active community back in its heyday but it’s more of a niche language than Clojure these days. That said, there used to be a lot of (US) government CFML code (back when the government often preferred proprietary systems with commercial support).

This is exactly the reason why clojure-style-guide seems to recommend it: https://github.com/bbatsov/clojure-style-guide#leverage-markdown-in-docstrings

Nice, I'm thinking about rendering docstrings as markdown on Chlorine/Clover