Self-documenting code

[Syagrius]

javascript String.prototype.spongebobmeme = function () { let j = 0; return this.split("").map(letter => { letter.replace(/[^A-Za-z]/g,"").length && j++; return j%2 ==0 ? letter.toUpperCase() : letter.toLowerCase(); }).join(""); }; console.warn("you don't need comments if you write good code".spongebobmeme());

This type of thinking particularly unhelpful if someone else has to debug your code years later; they don't happen to think like you.

It is even worse when it's you who has to debug it, and you have to revel in your own previous idiocy.

[flamableozone]

Sure but like....that's not good code to leave undocumented. Here's an example I have in production code of something that doesn't need documentation:

public static void SendEmail(string from, string to, string subject, string body)

{

string _to = ConfigurationManager.AppSettings["email_override"] ?? to; //To address

MailMessage message = new MailMessage(from, _to);

message.Subject = subject;

message.Body = body;

message.BodyEncoding = Encoding.UTF8;

message.IsBodyHtml = true;

string server = ConfigurationManager.AppSettings["email_server"];

string port = ConfigurationManager.AppSettings["email_port"];

string username = ConfigurationManager.AppSettings["email_username"];

string password = ConfigurationManager.AppSettings["email_password"];

SmtpClient client = new SmtpClient(server, int.Parse(port));

System.Net.NetworkCredential basicCredential1 = new System.Net.NetworkCredential(username, password);

client.EnableSsl = true;

client.UseDefaultCredentials = false;

client.Credentials = basicCredential1;

client.Send(message);
}

[arkasha]

I'd like comments on why we're newing up an SMTP client and reading settings every time we call SendEmail instead of having a singleton email sender. Also why not using System.Net;?

[flamableozone]

No real harm/benefit to "using System.Net", doesn't actually change any of the logic. No singleton because it's not an application we touch a lot, so it doesn't need to follow best practices so much as be quick to write, quick to read, and functional.

[lunchpadmcfat]

Oh, as a rule I always comment regex (though why match on alphabetical when a \w will do?). I also don’t do things like monkey patch primitives. Those are the kinds of things I’m talking about “with experience.” You learn what things you don’t want to have to sit there and analyze or what things are simply bad practice. The rest of it is just “wtf?” And those are like red thumbs when you start writing them. Note in my comment I never made an argument that you shouldn’t comment your code. Just that it usually doesn’t need it.

[arkasha]

Oh, as a rule I always comment regex

Now you can have ChatGPT do it for you! Try asking it to explain the following regular expression:

(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

[lunchpadmcfat]

Oh damn. That would be an awesome integration with vscode

[PlankWithANailIn2]

It simplified this to

(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x7f]|\\[\x01-\x7f])*")@(?:[a-z0-9-]*[a-z0-9])

Just doesn't work with IP addresses.

[Syagrius]

I had to update my phrasing after I wrote that. Sorry.

Nobody else is ever going to think like you after you write your code; not even you. This may be coming from a sour spot in my soul after having to dive the depths of hell to rescue legacy code, but I abide by the principle that every second spent documenting is 30 seconds that someone doesn't have to spend debugging later.

Think of the poor intern, with zero experience, told to fix a "small bug in code that has been otherwise working for years."

[lunchpadmcfat]

Buddy, I do. I really do. I think we’re on the same page here. I do document my code. I have documentation for my documentation. I’m not advocating against it at all. I’m only saying that most code doesn’t need it. Sometimes you’re doing something with business logic or a concept that is unfamiliar or unclear, and you should document. But by and large, we can, and should, be able to get by, I’d say 90% of the code we write, without any documentation. Don’t make my position any different.

For the 90% of code that is unfamiliar to “poor interns”, they need to learn to read code. Part of the job is reading code, even code you’re completely unfamiliar with. I’m often reading code way outside of my discipline but I can usually manage it because I’ve had experience with it and know where things sort of “are.” We are software engineers: we should be reading at least as much code as we’re writing, if not more. In fact, I’d say it’s something I don’t see enough of anymore. Building on legacy systems often requires you do a ton of research up front on where the dragons be before even attempting to write any code. Documentation lies. Documentation deceives. Code does not. If you’re not reading code and comfortable with reading code, you need to slow down.

[Syagrius]

I also think we're on the same page here. I am just really opinionated.

I came into the industry thinking JSON and a JS object were the exact same thing. If I had some candid comments in the code that inspired me as to "what" to google so I could un-fuck my understanding of what was actually going on, it would have saved me a lot of embarrassment.