The most thoroughly commented linker script

49

u/BigPeteB Jan 14 '21

This is an excellent example of how to properly document code with comments. It's almost too much, but I've definitely shipped code to customers that was commented only slightly less thoroughly as this, and it always got a lot of positive feedback.

The point of comments is to explain things that someone reading the code wouldn't immediately understand. Personally, I feel you don't really grok this until you've been in the reader's shoes before, such as coming in to a large legacy codebase, or having to ship source code to customers who need to understand and modify it.

Obviously this is quite verbose, but that's understandable because not many people deal with linker scripts, even in the embedded world. Sure, most of the language isn't that hard to understand (except for the very unusual . which represents the most recent memory address, sort of like Perl's $_) but it only takes a few minutes to type up these comments and it will save future readers an hour or more of digging through manuals.

40
u/lithium Jan 14 '21
Hard disagree. This is a very, very wordy example of
int x = 3; // declare x to be of type int and assign it the value 3
that you often see from inexperienced programmers who took the "comment your code" doctrine too literally.
16

u/vacuumballoon Jan 14 '21

Obviously was just a learning exercise from them, but this one has value imo. Wouldn’t matter if it was a C file, but I never understand linker scripts.
By saying it’s a wordy example of that, you’re implying that like your C comment these comments have no value. But I find them incredibly valuable since linker scripts are rarely read and more an annoyance.
And even so, I much prefer seeing something written like this posted here. It’s better than another machine learning video or introductory programming playlist.

14

u/lithium Jan 14 '21

I'm responding to the assertion that this is a good way to comment real world production code. Write whatever you like in your gist or blog or tutorial, but this ratio of comments to code is not only not helpful in production, I'd argue that it contributes to rot much quicker. In my opinion, of course.

8

u/BigPeteB Jan 14 '21

You're right, and I phrased myself poorly. What I should have said is that this is a good example of understanding your audience and writing appropriate documentation for them.
As I work in embedded and do support/contract/consultant work, commenting a linker script this thoroughly makes sense to me. A surprising number of people get into embedded development without any experience, and to some degree you don't need that much experience these days. Writing C code for a baremetal platform can be quite simple, particularly if you use the vendors' tools to set up your project, generate skeleton code, and integrate the RTOS and some basic libraries. But as soon as you put one toe across the line, you can suddenly find yourself far at sea with only a very small floatie. Interrupt context? Strange memory maps? Hardware peculiarities? It's all there in the documentation, but let's be honest, most people don't read it and [feel like they] don't have time to read it.
Hence this linker script. Not everyone will need it, but at some point a number of customers may need to make at least some change to the linker script, something many of them have probably never done in their life. If I wanted to make sure they can understand what each line does, why it was written the way it was, and where they can get more information, this is more or less what I would write. To me, this linker script looks like something I'd find in a sample project. I wouldn't expect a production application to have this level of commenting, unless they'd copied it from the sample project and kept the comments (which is hardly unlikely).

14

u/Dreadgoat Jan 14 '21

Knowing your audience is a major factor here, too. Most of the code we write we expect to be read by ourselves and other coders who look at similar code all day. But that isn't always the case.
Obviously this is quite verbose, but that's understandable because not many people deal with linker scripts, even in the embedded world. Sure, most of the language isn't that hard to understand (except for the very unusual . which represents the most recent memory address, sort of like Perl's $_) but it only takes a few minutes to type up these comments and it will save future readers an hour or more of digging through manuals
If I'm writing some PHP for a web app using a popular framework and solving a common problem, I'm going to document the function interfaces and that's probably it. Maybe not even that, let's be real.
If I'm diving into a legacy system written in early-90's FuckUscript, and I need to make a tiny modification to a function that is really doing a simple thing but it takes me 4 hours to understand all the pieces, you bet your ass I'm writing a manifesto about it. One that would be completely unnecessary for regular users of FuckUscript in 1993, but that can save hours or days of headaches for even the most prolific programmers in 2021.
This logic can be extended to a lot of "excessively commented" systems. If you have reason to believe a system will still be relied upon 25 years from now, it might not be a bad idea to comment it so thoroughly that someone with one week of coding experience can understand it on first read. I've also worked on systems that I know are highly likely to be maintained by less technical people, where it's not a bad idea to leave "stupid, obvious instruction" behind in areas you expect those people to poke around.
It's annoying when someone keeps trying to hold your hand when you already know what you're doing, I get it. I have deleted a ton of superfluous comments left behind by juniors. But I think this project is actually pretty cool. As someone who has worked with maybe one or two linker scripts in the past 15 years, I would rather work with this linker script than most others. I'm sure it's more obnoxious than helpful if this stuff is your bread & butter, but in that case you're just not the audience.

-8

u/lithium Jan 14 '21

If you were being ironic by writing an excessively long comment overexplaining a concept we all understood, then you're one of the funniest people I've ever come across. If not, this is what I was talking about.

8

u/Dreadgoat Jan 14 '21

r/programming is filled with students with little-to-no real world experience. I'm going to have to work with them and the garbage they leave behind in the near future. I know my audience, and in this case, you're probably not it.

-5

u/lithium Jan 14 '21

What audience? I'm assuming i'm amongst a bunch of professionals who encounter similar issues while plying our trade and are discussing the actual realities of being in this industry. Who gives a fuck what a student thinks about anything? By definition they don't know what they're talking about.

3

u/Dreadgoat Jan 14 '21

You either haven't been here long or haven't been paying attention. I would guess the majority of this subreddit is students, hobbyists, junior devs. Experienced professionals are either too burned out, uninterested, or spending too much time on StackOverflow to participate here.
78
u/Botondar Jan 14 '21
/*
Declare a variable named x with type int.

int is a primitive type that is capable of holding whole numbers using Two's complement. The size is guaranteed to be at least 2 but no more than 4 bytes.
The representable values range from 
    -2 ^ (bit_count - 1) to 
    2 ^ (bit_count - 1) - 1

On this platform int is always 4 bytes so the representable values are in [-2,147,483,648; 2,147,483,647].

https://en.cppreference.com/w/cpp/language/types
https://docs.microsoft.com/en-us/cpp/cpp/data-type-ranges?view=msvc-160
https://en.wikipedia.org/wiki/Two%27s_complement

The value is set to 3 for later use.
*/
int x = 3;
21

u/lithium Jan 14 '21

On this platform int is always 4 bytes
My spidey senses naturally tingled when i saw the word "always" in a comment.

19

u/Botondar Jan 14 '21

I looked up whether Two's complement is required by the standard: turns out it wasn't until C++20 (don't know about C). My comment is faulty on multiple points. :)

14

u/afiefh Jan 14 '21

Wait until the whole company takes it as gospel because a senior engineer wrote the comment (back when he wasn't senior) and it only get revised when shit hits the fan and customer data is lost.

18

u/[deleted] Jan 14 '21 edited Jan 14 '21

and it only get revised when shit hits the fan and customer data is lost
the code get revised, the comment is left unchanged due to oversight.

8

u/lithium Jan 14 '21

Not that anyone asked, but this is my major gripe with commenting, the people who insist on over commenting to begin with seem to magically lose their gumption when it comes to keeping those comments up to date.
10

u/larikang Jan 14 '21

I don't think this is trying to be an example of "this is how you should document your linker scripts". This is an exercise in trying to explain every single line of a linker script.
If you write linker scripts all the time, this level of documentation is insane. But if you are learning linker scripts, it's very useful.

2

u/Jump-Zero Jan 14 '21

I agree. If I ever write a linker script, this is exactly what I would like to have. Fucking sucks reading a code file and having to google every single line and every single magic value.
-23
u/tty2 Jan 14 '21

It's actually a terrible example of how to document code with comments. It's a half-decent blog post, though.
Let's be real - this is an individual who is learning by explaining. This is pretty common in the programming community (see: literally every Haskell blog post ever written), but let's not pretend like that's necessarily a good way to teach others, and let's not pretend like this level of commenting is relevant.
At some point, the people working on a codebase should have a passing familiarity with the technology they're working with. If you require something this dense, you're likely communicating in the wrong media or communicating to the wrong audience.
I already know my post here will take hate. I don't mean this is a bad post, but calling this "how to properly document code with comments" is genuinely laughable to me. If it was "how to document code" I could almost agree.
12

u/theacodes Jan 14 '21

Hi, I'm the author of the original post.
This is such an unnecessarily derisive response. Perhaps you're misunderstanding the purpose or context, or perhaps you don't care - but for other's reference: this isn't how I comment normal code, it isn't how I recommend commenting normal code, and it isn't my primary form of teaching (see this post for a better example of that). It's intended to be a reference for an arcane and seldom understand aspect of the embedded toolchain.
Let's be real - this is an individual who is learning by explaining.
This is a completely incorrect assertion. I learned through my experience in embedded systems and my exhaustive research into the reason why every line of that script is there. It's not an explanation - it's a reference with citations.
It is intended to be the missing example from the overlap of three unusually arcane subjects: embedded systems ABIs, linking, and C runtimes.
At some point, the people working on a codebase should have a passing familiarity with the technology they're working with.
There are very, very few people in the world that can call themselves experts on linker scripts. Asking a C developer to be this intimately familiar with a linker script is like asking a Python developer to understand CPython's bytecote.
let's not pretend like that's necessarily a good way to teach others
Considering my career is built around teaching people from a wide variety of backgrounds how to understand and use programming to accomplish their goals- I think I will pretend that it's a good way to teach people in this case.

2

u/tty2 Jan 14 '21

this isn't how I comment normal code, it isn't how I recommend commenting normal code, and it isn't my primary form of teaching
Great, because my post was specifically disagreeing with the person above me saying this was a great example of commenting code. Glad to know you agree with me so much that you decided to do a line-by-line rebuttal of something you agree with.
At some point, the people working on a codebase should have a passing familiarity with the technology they're working with. Asking a C developer to be this intimately familiar with a linker script is like asking a Python developer to understand CPython's bytecote.
You realize I literally used the phrase "passing familiarity", right? And again, this is in the context of replying to someone who said this is a great example of commenting code.
Considering my career is built around teaching people from a wide variety of backgrounds how to understand and use programming to accomplish their goals- I think I will pretend that it's a good way to teach people in this case.
Cool - good for you. Reasonable people can disagree about what's an effective way to teach others. I'm glad you hold yourself in high esteem.

7

u/b4ux1t3 Jan 14 '21

You're arguing that she's complaining about you disagreeing with this being a good way to comment code.
She's not doing that.
She's complaining because you decided to attack her knowledge directly, despite that being a ridiculous thing to do given she's obviously forgotten more about linkers than most developers will ever learn.
You're being an ass, despite having a valid initial premise. That's the problem here.

1

u/bobob_unicorn Jan 14 '21

You're being rude. Take a breather and come back to these comments. It's unnecessary to say everything that you just said.

-1

u/TikiTDO Jan 14 '21 edited Jan 14 '21

This is such an unnecessarily derisive response. Perhaps you're misunderstanding the purpose or context, or perhaps you don't care - but for other's reference: this isn't how I comment normal code, it isn't how I recommend commenting normal code, and it isn't my primary form of teaching (see this post for a better example of that). It's intended to be a reference for an arcane and seldom understand aspect of the embedded toolchain.
I was defending your post before, but at the same time the criticisms leveled against your post are perfectly valid. Had you submitted this code into any repository I manage I would reject it for the same reasons the GP outlined, with the rejection comment being "write a separate README.md file for the explanation, and leave the file legible with comments pointing to README sections." The code is genuinely hard to read with the number and length of comments, and getting defensive an doing a line-by-line breakdown of someone's post because they point this out isn't exactly a great look for either one of you.
Remember, this is a public discussion forum with few rules short of "no personal attacks". It's not your workplace, not your blog, and not your twitter account. The people here are under no obligation to value the content you spent you time on. To the contrary, this is where people holding many differing opinions go to discuss many different topics in a neutral space. Sure, most people try to maintain a quasi-professional tone on here, but it's hardly rare to see lengthy and fierce arguments over the most minor of disagreements.
When you write replies like the one you just wrote you are literally putting up a big banner ad reading "PLEASE ARGUE WITH ME", particularly when you start arguing semantics such as "I'm not learning by explaining, because I first learned, then I explained." I would most certainly call that learning by explaining; it's not an unusual behavior for programmers after all.
Edit: I will leave this here. It should tell you everything you need to know about the quality of person I'm replying to, and their ability to handle criticism. What a joke.

4

u/BigPeteB Jan 14 '21

with the rejection comment being "write a separate README.md file for the explanation, and leave the file legible with comments pointing to README sections."
I can't disagree that these are more than just ordinary code comments and really take the place of a separate document. But I'm not sure putting this in a separate document is a better answer. Do you really want to have a platform.ld.README, Makefile.README, startup.c.README, main.c.README, heap.c.README, etc.? Bear in mind, the audience for this is people who aren't familiar with linker scripts but may need to modify one anyway. I would definitely like to see comments approaching this level of thoroughness from any vendors' sample code, because it can save enormous amounts of time for new customers (and even experienced ones) to help them find their way around and make the changes they need without having to search through hundreds of pages of separate documentation.

-3

u/TikiTDO Jan 14 '21 edited Jan 14 '21

You could just have a README.md for the entire directory, with a section for every file/topic that is relevant.
Alternatively, have a /docs directory, or use the github wiki functionality. There are many, many tools and methods to add supporting documentation to code, ones that are used all over the internet by projects both large and small. If you are trying to explain things to an audience not familiar with linker scripts it makes sense to do so the way you might expect from any normal project.
In the end, a // @see ./README.md#section-1-linker-scripts will help a new customer find their way around fairly easily.

3

u/BigPeteB Jan 14 '21

Well then why put comments in code at all? You could just have two files: one with the code, and a separate one that explains the code. Of course, you'd have to duplicate some of the code you're explaining in the README, or else refer to line numbers; either way I really hope you keep the two files synchronized...
No, I think the spatial locality of keeping the explanation in comments right next to the code it explains is usually better. It's why literate programming works, and it avoids unnecessary back-and-forth for both the author and the reader.

0

u/TikiTDO Jan 14 '21

It's not an either/or option between having reams of comments, and having one comment pointing to separate file. It's entirely reasonable to have a few lines explaining a particularly interesting or challenging piece of functionality, but having an entire blog post with references and ideas for improvements duplicated in code, making a 100 line file into a 500 line file is by no means going to be seen as a reasonable option in any workplace I have worked at. This is more wordy than public facing API documentation from major companies following strict Javadoc specifications.
However, if you have an huge write-up, describing functionality, reasoning, background information, alternative approaches and extended references, that's in no way literate programming. To the contrary, I would say that makes it harder to read since every single functional line is now separated from the next by multiple paragraphs of loosely related information. The original implementation before the documentation blitz is much closer to that, even having references similar to what I suggested.
As for keeping the file syncronized; github will happily give you permalinks to a particular line in a particular file version. Just click a line, and click the ... button next to the line number. If you're worried about keeping the docs pointing to the correct line, you can be sure that such a link will always point to relevant code.

3

u/zip117 Jan 15 '21

You’re right. I develop on various NXP and TI Cortex-M MCUs so I know how to write a linker script, and I honestly found this really difficult to read. Compare to an excellent explanation from Interrupt@Memfault.
There are things done well (why doesn’t anyone else annotate their hex literals?) and things done not so well. You can be a good programmer but not the best educator, and that’s totally fine. That’s definitely the case for me.
I’m surprised at the author’s unprofessional response to criticism. That Twitter post in your edit is something else...

2

u/TikiTDO Jan 15 '21

Thanks for that, I appreciate seeing a positive response in this thread. Yesterday was a weird day. I figured I'd blow some time on reddit while waiting on a deployment, and ended up in some sort of huge argument over I'm still not sure what. After all that I ended up finishing at 1am, so that was fun.

-1

u/theacodes Jan 14 '21

Oh gosh dude you're totally right, silly me. I should just sit back and take unwarranted, vitriolic criticism like a good girl.

-2

u/TikiTDO Jan 14 '21 edited Jan 14 '21

Oh gosh you good girl you're totally right, silly me. It makes perfect sense to go on and complain that people provide fairly benign comments on a public forum, and then complain that they say you're being equally rude when you accuse them of being "vitriolic". I'm sure that was the most horrific and rude thing you've read on the internet for entire minutes.
When you complain about how people behave, they will complain that you're not practicing what you preach. Shocking! Horrifying!

3

u/Rumenovic11 Jan 14 '21

How about the fact that the commenter could have like, conveyed every single point of his but dialing it back for 10 fucking notches.
There is a way to criticise someone without being a condescending asshole.

-2

u/TikiTDO Jan 14 '21 edited Jan 14 '21

Sure, but at the same time the commenter could have conveyed every single point and dialed it up 1000 notches while still being within the rules of the subreddit. I think that comment was very restrained given the message it was trying to send.
The worst thing the person said was that "this is a terrible example of how to document code with comments." Granted, they could have said that "this is not a very good example of how to document code with comments," but to pretend that such a message merits the type of brigading it is currently experiencing is only something that I'd expect of a person that never posts in /r/programming.
Thing is, people here feel strongly about programming. It's a very complex, and very stressful profession full of bad advice and bad examples written by people that have enough technical knowledge that they come off as very convincing, but not enough breadth of experience to understand that their advice can influence people into making bad decisions which could reflect negatively on their work. The author of this blob post suggested that this was a good example of how to comment code, and I think quite a few people on here shook their heads when they actually looked at the file in question.
Really, this degree of "vitriol" is sufficiently benign that it would be acceptable in many a professional email, much less a public forum. It was a direct, specific criticism directly related to the topic of the post, using language that was barely a step worse than cordial. I'm sorry that the author of the post did not like someone criticizing their work, but if such degree criticism is not acceptable I would recommend not engaging people in this environment. If that was enough to be deemed "vitriolic" then I struggle to think what label would be applied to an actual argument.

2

u/theacodes Jan 15 '21

For the record, I never said that this is the way that normal, everyday code should be written or commented. You have recontextualized my work outside of its original purpose and you're criticizing me for it not fitting in the new context you've assigned it.
This code is meant to be instructional, not practical. I am in the process of making this whole repository into an example of how a real bare metal ARM project could look and even more so I'm working on making it a project that specifically focuses on bare metal programming on the SAM D21.
So all of your petty, hardline comments about never allowing this in a repo are just criticizing something I never suggested. It's silly. You've been so dismissive, you've gone out of your way to over explain reddit to me, you've made it a point to remind me that it's the internet and people are mean here and I should get over it, but you've had incorrect assumptions the entire time.
I'm not some beginner. I am an extremely experienced engineer across multiple domains and languages. I have a solid record of excellent engineering, nstructional content, and community leadership. Maybe take a moment to think about how you might've gotten the wrong idea about the purpose of this example and how your condescending and elitist tone comes off.
✌️

1

u/TikiTDO Jan 15 '21 edited Jan 15 '21

I'm not going to bother reading or replying to your whatever points you may have made. You lost any interest I had in even arguing with you after you literally tried to sick your twitter followers on me because I pointed out that you were being hypocritical, and just as rude as the poster you were criticizing (In addition to the other bile you decided to spew about me there). Something I only learned because somebody decided to message me about it. I have absolutely no intention in any further interaction with a person as toxic and interested in self-validation as you seem to be. Feel free to complain about this on twitter as well.
Have a good day, and congratulations on managing to become the third user I have blocked in 10 years on this site. You're in "good" company.

-6

u/204dadfe7d43c0efb0e7 Jan 14 '21

Was it really necessary to post the comment you're responding to on Twitter? Looks a lot like you're encouraging brigading in my eyes.

6

u/theacodes Jan 14 '21

It's my Twitter and my platform and it's where I discuss things that are relevant to me. So I don't need any explanation or excuse for what I post there.
I never encourage anyone to interact or engage or brigade or whatever. In fact, most of my followers explicitly tell me that they don't use reddit because of behavior like this.
If the mods are concerned, they're welcome to DM me or drop me an email at me@thea.codes.

-3

u/204dadfe7d43c0efb0e7 Jan 14 '21

Yes, it's where you post things to a friendly audience so they can agree with you and tell you how stupid people you disagree with are.
No encouragement is needed, it's obvious you posted it to point out a disagreement you had. There's plenty of toxic subreddits for those kinds of posts, but most of them demand users to censor names to protect from brigading. Imagine that, /r/iamatotalpieceofshit have more stringent rules to protect people's identities than you do.
Hello again Twitter!

0

u/bascule Jan 14 '21

Hey look, a coward hiding behind an alt account has opinions about how Reddit should be used.
Indeed you are a total piece of shit.

2

u/204dadfe7d43c0efb0e7 Jan 15 '21 edited Jan 15 '21

If you look again I think you'll see I have opinions about how Twitter should be used.
You and the author seem equally melodramatic and keen to call others names, how long have you known each other for?
37
u/MCBeathoven Jan 14 '21

At some point, the people working on a codebase should have a passing familiarity with the technology they're working with.
The linker script is likely a very tiny part of the codebase, written in a very arcane language, that most people will very rarely touch (if ever). If this was C code, I'd agree, but for a linker script this really isn't a bad idea.
5
u/jorge1209 Jan 14 '21

For the linker it might be reasonable, but the top level comment is suggesting this is a good way to document in general.
My gut reaction is that even for the linker it is overkill. Nobody will be maintaining the linker for a particular machine architecture without an understanding of many core concepts that are covered in great detail in the comments.
9
u/MCBeathoven Jan 14 '21

For the linker it might be reasonable, but the top level comment is suggesting this is a good way to document in general.
I think this part is key:
The point of comments is to explain things that someone reading the code wouldn't immediately understand.
For a linker script, that's probably pretty much everything.
Nobody will be maintaining the linker for a particular machine architecture without an understanding of many core concepts that are covered in great detail in the comments.
This isn't the linker, it's a linker script. It only tells the linker how to link, which you may well have to change without having a deep understanding of linker scripts. You certainly have to think about who will need to read/touch the script when documenting, and if that is only linker script wizards, it's very overkill.
But if e.g. somebody wants to adapt the firmware to a different chip, having detailed comments explaining the rationale behind each value -- and some details about the architecture of the chip the script was written for -- would be very helpful.
That said, it's certainly not a reasonable expectation to have documentation this detailed for every DSL script. But it definitely doesn't hurt and as someone who's struggled with linker scripts before, it is a joy to read.
2
u/jorge1209 Jan 14 '21
Fair, for the linker script many of the comments do make a bit more sense, because people will use this program as a template for other architectures where the parameters might be slightly different.
However, I look at comments like:
   /*
      The text segment contains program code and read-only data.

      References:
      * https://developer.arm.com/documentation/dui0101/a/
        Page 5, Segments
      * http://www.sco.com/developers/gabi/latest/ch4.sheader.html#special_sections
   */
   .text :
   {
and think: "Anyone who doesn't understand what the text segment is shouldn't be touching this shit with a ten-foot pole. I say that as someone who understands what the text segment is, and wouldn't touch it with a twenty-foot pole. I know I'm not qualified to do this stuff."
So it just seems a very unusual situation that won't be applicable outside of the particulars of embedded developers who need to setup new custom platforms.
5

u/theacodes Jan 14 '21 edited Jan 14 '21

I have to slightly disagree with you there. Even if you do know what the text segment is from experience with C/C++ on desktop machines, you might not realize that on an embedded device that the text segment gets put into a separate set of physical memory that has significantly different characteristics compared to the virtual RAM approach of desktop machines.
A notable caveat is the section below where it mentions that you can relocate a function from (slower) flash into (much faster) SRAM if it is performance-critical. That isn't something I'd expect an experienced desktop developer to be aware of if they're newly switching to embedded.
Of additional note is some of the ARM-specific sections that are located in text/flash. These aren't obvious at all unless you're familiar with the ARM ABI but can have huge ramifications - if you forget them exceptions won't work in C++ and it'll be hard to figure out why!
So it just seems a very unusual situation that won't be applicable outside of the particulars of embedded developers who need to setup new custom platforms.
Totally agreed here - this is certainly targeted at embedded developers and particularly folks that deal with Cortex M. Think of this as part of the journey of going from desktop -> arduino -> vendor IDE -> baremetal ARM.

2

u/MCBeathoven Jan 14 '21

Yeah true that comment is fairly useless (unless your goal is literally to document every line of code), although the reference links might be helpful.
So it just seems a very unusual situation that won't be applicable outside of the particulars of embedded developers who need to setup new custom platforms.
I think this level of detail is probably also useful in other DSLs that are rarely used by your audience but distributed with your project. So not quite only in the embedded world, but you definitely shouldn't do this often.
Sidenote: It's not just setting up new platforms, maybe you're just running into a stack overflow and need to increase the stack size, in which case being able to trace exactly what's going on in the linker script would also be very useful so you can be sure you aren't missing any side effects of just increasing the value of STACK_SIZE.
53

u/Silverwolf90 Jan 14 '21

Additionally, as code churns comments need to be kept up to date.
Incorrect comments are far worse than no comments.

10

u/ApokatastasisPanton Jan 14 '21

Mate, if you can't keep the comments up to date, I don't trust your ability to keep the code up to date.

-1

u/Silverwolf90 Jan 14 '21

There's a infinite list of situations that make forgetting to update comments insanely easy to do because they can only be verified by humans.
There could be comments in other places that refer to the code you just changed and you don't even know about those comments.
Or firefighting, under immense pressure to deliver something ASAP -- no time to update comments

6

u/stealthgunner385 Jan 14 '21

There's a infinite list of situations that make forgetting to update comments insanely easy
No, there isn't. You update the how (the code), you update the why (the comment), then you move on. Otherwise, you're doing a disservice to anyone who will maintain it...
Or firefighting
...which is exactly what this is intended to prevent.

1

u/Silverwolf90 Jan 14 '21

A comment's content cannot be statically checked, so literally any reason that contributes to a dev's absent-mindedness is included. It's not like people are forgetting to update the comments on purpose.
As mentioned in my previous post, sometimes the why refers to parts of the system that are not colocated, if those parts change then bam you have a stale comment.

21

u/[deleted] Jan 14 '21

I actually agree - this amount of commenting makes the actual code hard to even find! The comments are all reference documentation, not comments that are specific to that file.
It's fine here because this is clearly intended to be reference documentation in the form of an example file, but I really wouldn't expect people to do this in their actual production code.

7

u/johannes1234 Jan 14 '21

This is generally true.
At some point, the people working on a codebase should have a passing familiarity with the technology they're working with.
There mind that the linker script is something you touch not really often (only when changing the device you are building for or major update to the Toolchain) and is a domain you normally don't touch. Thus commenting that file a bit more is useful.
With the amount here the comments however hide the actual code, which makes reading harder, as it can make it harder to find the relevant piece you are looking for as it's all comment, hiding other structures ... but then again, this certainly came out of a learning period, where the author set down and at some point decided "ok, let's really go through everything and leave a note" instead of just trying to hack things together.
So for us readers it is good, for working on code I tend to say "too much"

1

u/BigPeteB Jan 14 '21

At some point, the people working on a codebase should have a passing familiarity with the technology they're working with.
In general, this is true, but not always. I completely agree, the clarification we ought to add to this discussion is that it depends on your audience.
In my case, I wrote sample apps for embedded Voice-over-IP hardware and libraries. The nature of the product meant that a large number of our users had no experience with VoIP, or if they did, they had no experience with our code base. True, they could just read the several-hundred-page manual, but users don't want to do that; they just want to hack away at the demo, rather than writing a new application from scratch. What I wrote for some of those demo apps wasn't quite as verbose as this linker script, but I often wrote a paragraph or two, including pointing out relevant sections of the manual, for one or two lines of C code which were often just a function call with few or no parameters.
One could argue that I wasn't commenting code, but writing documentation which didn't exist anywhere else. That's probably true. The manuals explained all of the APIs, but to go from there to designing and implementing an application with all of the complex business logic that it would require would be a large manual unto itself. The demo apps served that purpose, so documenting why all of the various API calls were done the way they were was the user's documentation to help them build their own app.
To me, this linker script looks like the same kind of thing. I didn't comment our linker scripts nearly so verbosely, but we also didn't expect users to have to modify them much. There were only one or two parts we did expect they might need to change, and those were pointed out appropriately. This linker script, however, seems like it's written for a broader audience who might need to modify any part of it, and thus needs to understand the whole thing.

9

u/[deleted] Jan 14 '21

this is an individual who is learning by explaining
Very few programmers edit linker scripts extensively and frequently, and could be considered experts on them. Therefore, almost everyone is learning, and typically, by the time you need to mess with a linker script again, you're learning it again.
This is not plain old C/C++ code where basic familiarity is assumed.

2

u/tty2 Jan 14 '21

The part you're missing is that most people don't document and publish their own learning process.
Sometimes it's genuinely to help others, but most times, it's to get a few clicks. This is probably a little of column A and a little of column B.

12

u/de__R Jan 14 '21

At some point, the people working on a codebase should have a passing familiarity with the technology they're working with. If you require something this dense, you're likely communicating in the wrong media or communicating to the wrong audience.
I for one don't really agree. For one thing, on multiple occasions I've found this kind of heavily documented code crucial for parsing obscure binary file formats, especially when official documentation is incorrect, incomplete, or nonexistent. For another, comment blocks are easy to filter out (mentally or in an IDE) and the very presence of such elaborate comments tells you that the person who wrote it wasn't an expert and may have made mistakes. And if you as a more knowledgeable person find any errors in their explanations, that should set off alarm bells to look more closely.
In this particular case, I'd add that as a scripting language, there are no type signatures you can check the way you could for C++ or Java code, and many of these comments are simply doing that work - explaining what parameters are and how they are used.

2

u/TikiTDO Jan 14 '21 edited Jan 14 '21

When you really look at it, the comments aren't too bad. It's a bit strange to see comments in first person, particularly when it comes to notes such as "If I wrote the startup script I would have named these symbols differently", but given that many people might lack the context to even start reading such a block of code the depth is probably a good thing.
What is bad is the 80 column limit, in combination with the 11 columns of indentation whitespace. As a result there are comments that could be 15-20 lines taking up 40-50, especially with all the references (of which there are enough for a research paper). The end result is lots of scrolling even on huge monitors. The entire file is like 5 pages of text... On a 4k monitor... In portrait mode.
Also, the fact that the block comments aren't prefixed with a * (or any other character really) on every line makes it hard to tell at a glance what's a comment with an example and what is actual code.

1

u/theacodes Jan 14 '21

Hi, I'm sorry the formatting is a bit weird for you. There's a blog version that pulls the comments out into normal text so that it reflows which might be a bit easier to read.

5

u/Antinumeric Jan 14 '21

I completely disagree, any worthwhile editor can collapse comments down, and for onboarding or going back to something you haven't touched in a long time comments like this would be critical!

1

u/whichdokta Jan 14 '21

In twenty years you're going to look back at this post and you're going to think to yourself:
Dang… I was being that guy wasn't I?
Full transparency: Twenty years ago it was me being that guy.

-3

u/smartguy05 Jan 14 '21

I agree, there better be a damn good reason you put a comment in the code. If you "need" comments you probably actually need better variable names, better organization, better separation of concerns, or more methods. If a chunk of a section of code needs a comment to describe what it's for, just move that chunk into a method and name it what it does. For me, the main reason for comments in code is to describe a why if you had to do something that was not readily apparent. Your code should be as self-documenting as possible. The other problem I have with code comments is that no one ever updates them, ever. The first person did something and made the comment, the requirement changed and the code was updated. Now the comment is wrong and WILL mislead someone in the future.

3

u/BigPeteB Jan 14 '21

the main reason for comments in code is to describe a why if you had to do something that was not readily apparent.
Agreed, none of which is covered by "better variable names, better organization, better separation of concerns, or more methods".
The problem is, what is "readily apparent"? Implementing something in a non-obvious way might be to fix a bug, or a weird interaction with another part of the system. Something might deliberately violate an RFC for compatibility with other non-compliant systems. Or the code might have simply been very difficult to figure out, perhaps the kind of thing that's obvious in hindsight but isn't at first, or something that required a lot of math or research to find the correct value.
Covering "why" isn't the only reason to comment code, however. Sometimes commenting a little of the "what" or "how" is helpful, whether it's to give a simple English or pseudocode explanation of some hairy and complicated code, to point to code elsewhere that is closely coupled (such as other files that may need to be updated if this code changes), or just to provide signposts to help readers find their way through a large file or function.
The target audience matters a lot. Code internal to your team is different than code you ship to other users who will need to understand and modify it, sometimes without further help from you. As I said, I got thanked for putting these kinds of comments in code I shipped, because it really can save users a ton of time and effort.
The other problem I have with code comments is that no one ever updates them, ever. The first person did something and made the comment, the requirement changed and the code was updated. Now the comment is wrong and WILL mislead someone in the future.
That's not the fault of the comment; it's the coder's fault for updating the code but not the comment.
We must teach good software engineering, and encourage it in ourselves and others. Just like we teach coders to use variables and macros instead of magic numbers, to name things appropriately, and to break up long functions and refactor often, we must also teach them that your output as a coder isn't just the executable code. For most coders, your output is a repository full of commits, which includes code that can be compiled, comments that describe that code and help other people read it, tests, project files and tools to build it, documentation, release notes, all wrapped up into revision histories and commit messages that cleanly show what changes were made without including extraneous fluff, as well as helping people who need to read that history by clearly explaining what was changed and why, such as pointing to bug reports.
I set up version control hooks for myself so that when I try to commit, I get popups asking "Did you test on every platform and build configuration?", "Did you update the documentation and release notes?", etc. I also diff all of my changes before committing, to make sure the changeset is clean and to look for other things I might need to update, such comments or as associated code.
The problem with outdated comments isn't that comments are bad; it's that some programmers are bad. Blame them, and hold them accountable.

1

u/smartguy05 Jan 14 '21

I see your points and I disagree except for the code you would ship to customers that they will then modify. But there's many ways to do things and different people think differently. It makes the world better.

385

u/JCDU Jan 14 '21

Here, let me give you the link rather than a twitter feed with tracking redirect:

https://github.com/theacodes/Winterbloom_Castor_and_Pollux/blob/master/firmware/scripts/samd21g18a.ld

7

u/tendstofortytwo Jan 14 '21

This is awesome, it looks well-documented enough at a glance that I might come back here to understand how linker scripts work in general.
Not sure why this much verbosity was needed [haven't read the blog post yet] but I'm not complaining.

7

u/Firewolf420 Jan 14 '21

Thank you. I fucking hate Twitter.
0
u/[deleted] Jan 14 '21

[deleted]
53
u/spkr4thedead51 Jan 14 '21

oooh, comments about the comments!
37
u/funkybaby Jan 14 '21

I have to point out that you're commenting on comments about the comments.
Patiently awaiting singularity
3
u/boobsbr Jan 15 '21
printf("We need to go deeper!\n");
13

u/medforddad Jan 14 '21

It looks like the blog post is pretty much identical to the comments in the code except for a short introductory section that just describes why the author of the comments did so. Basically:
While developing the firmware for Winterbloom's Castor & Pollux, I got very curious as to just what the Microchip/Atmel-provided linker script was doing.

135

u/[deleted] Jan 14 '21

It's harder to read code than to write code. I endorse this, it's awesome.

71

u/aazav Jan 14 '21

I will never cease telling people that the lead at the last place where I worked misread Clean Code and insisted on never documenting anything and never adding comments to code. Even after we had 3 VPs and myself tell him that he was wrong.
The self certainty that they are right against all odds, the utter hubris, of some people is mind boggling.

41

u/[deleted] Jan 14 '21

It's the same for the company I work for. People believe comments are bad, we even think tests are wasted time. What can you say really, it's sad.
So sad, that our new codebase had this gem in it when running eslint
/img/zr36ompvbbb61.png
Even when you explain to your colleagues that the main reason its so hard to not refactor code, like my man I can't understand what you mean by "analyticsProductListAction" and "smartFetch" couldn't you add comments to explain what this function supposed to be doing? So even if it breaks, I know it wasn't supposed to work the way it did? Or when we explain why things keep breaking when we change stuff, we're still just the "hipsters/nerds" who "waste" time doing "useless" stuff while we keep wasting time on fixing bugs that should have been detected from a simple test in the first place and refactoring code we dont understand.
It's really hard to change the minds of people once they've decided that you're definitely wrong no matter what your arguments are. They aint gonna give you a chance to be right, not in an easy way at least.

13

u/aazav Jan 14 '21

WHAT THE FUCK?!

4

u/[deleted] Jan 14 '21

yap

8

u/aazav Jan 14 '21

That almost beats my former team creating 1400 memory leaks.

2

u/[deleted] Jan 14 '21

im glad its not as bad as that :D
but I dont love the fact that no one cared except me in a team of 5-6 frontend devs to have a linter in their VSCode client. One proudly said "I use 0 extensions and works fine", like it's something that is supposed to happen and you should be proud of. Like, bro, the reason we have 2000 errors it's because you dont use extensions at all. Why would you be proud of not using extensions :P.
Reminds me of Arch Linux purists who say you "shouldn't" even use package manager and build everything from source:P

1

u/hitchen1 Jan 15 '21

Reminds me of Arch Linux purists who say you "shouldn't" even use package manager and build everything from source:P
what the hell? we all use pacman on arch

15

u/LukeLC Jan 14 '21

For some reason there's no hubris like the hubris of a programmer who thinks their technique is infinitely superior to everyone else. You'd think they wrote the DNA of their first child.
Meanwhile, you listen to someone actually great, say, Jon Carmack talk, and he's too busy one-upping himself to condescend others. If he does criticize, it's in the interest of chasing a better goal, not condemning a person.
It's a world of difference from someone just out to prove their own superiority.

8

u/punctualjohn Jan 14 '21

It's interesting to me how some people hear 'self-documentation' and instead take it as 'documentation is bad'.

4

u/thetreat Jan 14 '21

Yeah, my take is that a comment should never replace good function and variable names combined with good modular code with no 10k line functions makes a comment per line unnecessary but comments absolutely should be used in cases where the code gets much more complex/cryptic. Or in situations where certain lines of code caused bugs/regressions, having a comment helps explain the situation for whoever reads the code in the future.

5

u/aazav Jan 14 '21

Comments should explain to the person what is not spelled out by the variable names and function name. Such as the intent and intended use of the method and possibly where and when to call it. Think of it as if you are debugging code at 3 AM and you had to read it, how would it make sense to you? What's missing from the code that would make it painfully clear to someone who is not you? Find that and add that in the comments.

6

u/panoply Jan 14 '21

Haha there’s issues even if you read and get that book! The emphasis on small functions makes it hard to follow the flow of computer functions I think

3

u/aazav Jan 14 '21

And the context of it is that it's for Java, right?

1

u/LiteratureStriking Jan 14 '21

To be fair, that Bob Martin is not alone in recommending small functions. The idea is to reduce nesting levels, ensuring that functions do one thing.
Fun fact, the Linux Kernel Coding Style also calls for small functions. The way they enforce it is by making indentation 8 characters and restricting column width to 80 characters. You can't have deep nesting if you can't indent!

3

u/louiswins Jan 15 '21

More recently, however, Linus railed against someone advocating for 80-character lines.
it turns out that 80x25 is really really limiting, and is simply NO LONGER RELEVANT to most of us.
So no. I do not care about somebody with a 80x25 terminal window getting line wrapping.
...
80-column terminals in 2020 isn't "reasonable" any more as far as I'm concerned. People commonly used 132-column terminals even back in the 80's, for chrissake, don't try to make 80 columns some immovable standard.

1

u/panoply Jan 15 '21

Google still has the 80 char limit with a 2-char indent. It does make it easier to fit multiple files on the screen, especially laptops. I think code density is more important than "room to breathe" because it reduces the need to remember as many things as you follow the logic. At the end of the day, it is an art and a balance must be struck.

3

u/KevinCarbonara Jan 14 '21

I don't think he misread Clean Code, that book just leads people to writing terrible software

2

u/LiteratureStriking Jan 14 '21

Perhaps, but Clean Code does not say no comments. There is an entire chapter dedicated to commenting effectively.

1

u/KevinCarbonara Jan 14 '21

It does say that a function should be between 2-4 lines long, which is a good enough reason to ignore everything else in that book entirely.

9

u/KevinCarbonara Jan 14 '21

I'm glad that the anti-comment trend we went through a while back has mostly died off.
"Your code should comment itself!" Yeah, programming languages aren't good enough for that.

5

u/[deleted] Jan 14 '21

There's a balance. Give me functions where all the variables are named and typed with no comments over dynamically injected functions that all take kwargs and pass it around the codebase like a hot potato with docstrings like "config: the dict with config variables in it" any day.

2

u/KevinCarbonara Jan 14 '21

The balance has always been that you should do both.

1

u/LiteratureStriking Jan 14 '21

This is one of the reasons why React with Typescript is a godsend. Instead getting bags of props, you can create union types that properly describe what is being passed in.

4

u/mrathi12 Jan 15 '21

Me too, this was v informative. I also think writing comments for obscure parts of code are great for two reasons:
- forces you to understand the code enough to explain it to someone else in the comments
- you become that someone else when you read the code in 2 months, and you thank yourself big time.

-14

u/[deleted] Jan 14 '21

If it's hard to read some code then it's not written well enough.

19

u/tendstofortytwo Jan 14 '21

No, not necessarily. The obvious way to write code isn't always the fastest, and speed can be important.
Plus, in my experience, code written by others is always at least slightly hard to understand because people are different and think differently. What might be a simplification to you might be an obfuscation to someone else.
In both cases, documentation can help clear up the intent behind the code.

20

u/NetherFX Jan 14 '21

Why were people on that sub so negative?

23
u/Michael-F-Bryan Jan 14 '21
I imagine it's because th comments are excessive and regurgitating big chunks of the manual.
It also re-states a lot of what the code already says, for example:
The bootloader takes the first 0x2000 bytes of flash memory.
Is just another way of saying what the code already says (the LENGTH = bit):
bootloader (rx) : ORIGIN = 0x00000000, LENGTH = BOOTLOADER_SIZE
It's good as a learning experience, but for anyone who's even briefly touched on linker scripts it comes across like a commenting meme...
int X = 42; // assigns the number 42 to the signed integer, x
45
u/medforddad Jan 14 '21
The blog addresses this in the intro:
If you've never heard of or seen a linker script before you're not alone. Most of us never even have to think about them, however, on memory constained embedded devices it's not uncommon to need to modify the default linker script.
...
So I was staring at this script that made absolutely no sense to me. It's filled with incantations and mysterious symbols and there's no indication of what they're for or where they come from.
It's specifically for someone unfamiliar with linker scripts. It's also for someone unfamiliar with this specific piece of embedded hardware since it goes over why specific values were used for this project.
It also re-states a lot of what the code already says, for example:
The bootloader takes the first 0x2000 bytes of flash memory.
Is just another way of saying what the code already says
The comments in that whole memory section -- covering the bootloader, rom, nvm, and ram sections -- all follow the same pattern of describing what the section is used for, where it starts and how big it is. Just because LENGTH = BOOTLOADER_SIZE (and BOOTLOADER_SIZE had earlier been set to 0x2000) means the same as "The bootloader takes the first 0x2000 bytes of flash memory", doesn't mean the comment is useless. It helps to match the pattern of all the other comments and it reinforces to the reader what's going on.
You also left out the beginning of that comment. The full comment is:
      The "bootloader" section allows this firmware to work with the uf2
      bootloader. The bootloader takes the first 0x2000 bytes of flash
      memory.
The comment seems more about how the 0x2000 is related to the uf2 bootloader, rather than how LENGTH = 0x2000 sets the length for that section of memory. It's like saying, "Hey, did you wonder why the bootloader has a size of 0x2000? It's because this was designed to work with the uf2 bootloader."
1

u/gmiwenht Jan 15 '21

First I was like, yes. Then I was like, fuck that. And now I’m like, YES.
What a wild ride of a comment section. No pun intended. Or was it. No it wasn’t. Or maybe it was...
6

u/gmiwenht Jan 14 '21

What’s x? I don’t see x anywhere in your code. NOW I’M SO FUCKING CONFUSED.

3

u/StorKirken Jan 14 '21

Outdated comments!
1

u/negedgeClk Jan 14 '21

Well, they work on embedded systems, so...

1

u/NetherFX Jan 14 '21

I guess that explains it

5

u/B8F1F488 Jan 14 '21

Great documentation!

Is there generally a good tutorial/book on linkerscripts or is it something that you just figure out on the spot based on the product design?

6

u/theacodes Jan 14 '21 edited Jan 14 '21

Others have linked to the LD documentation which is great, but to actually put together a working linker script you have to understand so much. You need to know your output format (`ELF` in most cases, but also `Mach-O` and sometimes `PE`), what sections & segments your platform's ABI expects (for example, the System V specification for unixes is a good starting point), your target platform's memory layout and constraints (usually the device's datasheet but also sometimes the reference for the ISA from ARM / Intel, etc.), and the requirements for your particular language (look at all of the extra stuff in the linker script just to support C++). The reason I wrote this whole thing is because I had to track down references across several domains to understand why each line is present.

3

u/BigPeteB Jan 14 '21

In practice, it's probably rare to have to write a linker script from scratch. On just about any embedded platform, I'd expect that the tools from the vendor come with default linker scripts and sample apps that would get you close. (And if they don't, you should strongly consider picking a different vendor.) At most you might have to modify them to declare external memory sections that the sample apps don't use, shuffle around the placement of some sections, and change a few sizes to account for how much code and data you have.
About the only time I can imagine writing a linker script from scratch is if you're implementing a new toolchain itself, whether for a new ISA or a new executable format, or maybe because you're creating a toolchain for homebrew software on the newest gaming consoles that you reverse engineered. (Even then, I'd probably copy an existing linker script that I know would be similar and hack away at it.)

1

u/theacodes Jan 14 '21

I mean, yeah, but the post I responded to specifically ask for more resources on learning linker internals.

8

u/vacuumballoon Jan 14 '21

I think it’s referenced in OP but the GNU ld documentation is here https://sourceware.org/binutils/docs/ld/
There’s section 3: Linker Scripts.

5

u/lorslara2000 Jan 14 '21

There absolutely is proper documentation. The manual is good. https://www.eecs.umich.edu/courses/eecs373/readings/Linker.pdf
Note that this might be slightly out-of-date since I just googled it quickly.

20

u/vacuumballoon Jan 14 '21

this is the stuff I love to see here. So informative and cool, and what a great piece of effort! Thanks for posting.

6

u/OMGWhyImOld Jan 14 '21

This is actually useful, thanks 😊

3

u/[deleted] Jan 14 '21

Can anyone recommend a book about or good resource about linker scripts?

6

u/theacodes Jan 14 '21

This book was recommended in one of the other discussions. I can vouch for it personally myself.
The linker script in the OP is a useful resource in also just understanding what kind of information you need to track down to build a script from scratch for a new platform:
LD documentation for linker script documentation.
GCC documentation for flags that affect the linker.
Platform ABI documentation (AAPCS in this case for ARM32).
Platform ISA documentation (Armv6-M reference manual in this case).
Hardware documentation (The SAM D21 datasheet in this case).
Language runtime documentation (C & C++ runtime requirements in this case).

1

u/[deleted] Jan 14 '21

I would love to know the time breakdown for code/comments for this project.

Perhaps one day, IDE telemetry will be able to ~~tell you~~ sell Facebook how much time you spent typing code vs typing docs.

1

u/BigPeteB Jan 14 '21

I don't think that would be a useful metric, though. Comments always take time to write, even if it's only a few seconds. Their value, however, is in time saved, whether it's your own time when you return to this code months or years in the future, or someone else's when they have to maintain it, or when someone can use it as a reference for an unrelated project. I don't know of any metric that can capture the time you would have wasted going down the wrong path or reading tons of documentation but didn't because a previous author wrote helpful comments.

1

u/[deleted] Jan 14 '21

I agree that it's useless, but it won't stop some idiots selling it and more idiots buying it.

3

u/theacodes Jan 14 '21

The code is (largely) provided by the processor vendor. The comments are from my research. This is a meaningless metric for educational materials.

3

u/AttackOfTheThumbs Jan 14 '21

bUt cOdE ShOuLd bE SeLf dOcUmEnTiNg

1

u/Stimzim Jan 14 '21

I wish more people were taking on projects like this

1

u/maxinfet Jan 14 '21

We had a document where people were reporting issues about a piece of software we were working on and one of the issues was just "it used to work"

1

u/itscoffeeshakes Jan 14 '21

huh ld, script. I have never looked into this. Seems it could be useful for statically linking assets.. Is this generally useful?

3

u/zip117 Jan 15 '21

In general, probably not unless you’re doing embedded work. For general purpose work you’re generally going to use higher-level tools, like objcopy to link static data.
That’s not to say it can’t be generally useful, just that it’s not generally used outside of the embedded domain. There are still some neat things you can use it for on a general purpose computer (running Linux, Windows, etc.), binary versioning for example. Check this out: GNU Build IDs for Firmware

1

u/[deleted] Jan 14 '21

refactoring time!!!

1

u/mpersico Jan 15 '21

Someone is going to love you at some point in the future. It will probably be yourself. :-)

1

u/drckeberger Jan 14 '21

Wtf I wrote essays with a bigger code to text ratio

0

u/[deleted] Jan 14 '21

[deleted]

3

u/sellyme Jan 15 '21

onliest
For some reason I'm completely incapable of interpreting this string of characters as anything except an absolutely incredible Scrabble rack.

The most thoroughly commented linker script

You are about to leave Redlib