off-topic 2021-05-31 | Slack Archive

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

teodorlu10:05:50

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.

👍 3

pavlosmelissinos11:05:59

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:

Alex Miller (Clojure team)12:05:40

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

👍 3

lread15:05:03

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

marrs17:05:39

Would be quite hard using Groff ;)

lread19:05:56

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

sogaiu09:05:47

i think the idea is slightly different from your description

sogaiu09:05:28

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

👍 3

pavlosmelissinos11:05:08

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.

pavlosmelissinos11:05:44

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

sogaiu03:06:00

oh good point!

vemv14:05:25

'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?)

👍 3

marrs17:05:25

People who hate PHP tend not to actually use it

marrs17:05:27

Referring to previous topic ^

manutter5119:05:49

well, that's not necessarily a coincidence.

😂 3

manutter5119:05:04

(<-- EX-PHP programmer)

phronmophobic19:05:28

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.

✅ 9

seancorfield20:05:03

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.

Joe21:05:31

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.

seancorfield21:05:01

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).

manutter5120:05:11

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.

👆 3

phronmophobic20:05:07

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

manutter5120:05:29

Oh yeah, big time.

manutter5120:05:03

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

seancorfield20:05:05

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

mauricio.szabo21:05:19

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

mauricio.szabo21:05:20

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...

vemv00:06:01

backtick-delimited code will be rendered nicely under clojure-mode other items not. But I still use bullet points since they're readable anyway

seancorfield21:05:34

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).

kokada22:05:26

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

seancorfield21:05:09

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

lread21:05:55

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

mauricio.szabo23:05:43

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

2021-05-31

Channels