One thing I actually like about documenting my code
-
I a new person and coding it’s new and it difficult any tips .
Pick a language - I'd personally recommend C# as it forces you to correct syntax errors before you can run code, unlike Python or PHP. Then get a course, or a book and follow it from beginning to end, doing every exercise. This may also help: How to Write Code to Solve a Problem, A Beginner's Guide[^] - it gives you a technique to get you started on a problem.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony "Common sense is so rare these days, it should be classified as a super power" - Random T-shirt AntiTwitter: @DalekDave is now a follower!
-
I did say earlier that it's an unenviable task. It's such a chore. But, documenting my code forces me to review it. Just writing out how to use it uncovers areas for improvement. I've added several critical features to my UIX library as I've set about documenting it. I also shored up some function names that were out of step with my conventions. :)
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
honey the codewitch wrote:
Just writing out how to use it uncovers areas for improvement. I also shored up some function names that were out of step with my conventions.
I've had that happen myself. I'll notice little inconsistencies in how things are implemented, usually the sort of thing you refactor after some experience with the code. If a class is sufficiently complex, it's as if it forms a grammar. Making sure the right things are "nouns" and "verbs" and are named appropriately is sometimes easier to see when you're talking/writing about the code rather than creating the code itself.
Software Zen:
delete this; -
Pick a language - I'd personally recommend C# as it forces you to correct syntax errors before you can run code, unlike Python or PHP. Then get a course, or a book and follow it from beginning to end, doing every exercise. This may also help: How to Write Code to Solve a Problem, A Beginner's Guide[^] - it gives you a technique to get you started on a problem.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony "Common sense is so rare these days, it should be classified as a super power" - Random T-shirt AntiTwitter: @DalekDave is now a follower!
And don't start with an IDE. Start with a basic text editor until you get a little bit of the hang of it. IDE's can do too much for you.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
-
I did say earlier that it's an unenviable task. It's such a chore. But, documenting my code forces me to review it. Just writing out how to use it uncovers areas for improvement. I've added several critical features to my UIX library as I've set about documenting it. I also shored up some function names that were out of step with my conventions. :)
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
I don't document the code, so much as document the application/utility -- such as how to use it, how to specify command-line parameters or write a script. But, yes, that often leads to reviewing the code and making improvements. In some cases, I begin with a document of the list of features I want and such.
-
I did say earlier that it's an unenviable task. It's such a chore. But, documenting my code forces me to review it. Just writing out how to use it uncovers areas for improvement. I've added several critical features to my UIX library as I've set about documenting it. I also shored up some function names that were out of step with my conventions. :)
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
I look at my app, and if something needs documenting, I figure it's probably too hard and should be rewritten. My documentation mostly consists of (control) tooltips. I used to create elaborate help files (using Help Workshop, etc) until someone decided to condense my help into a "guide" ... sort of like ketchup on one's filet mignon.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
And don't start with an IDE. Start with a basic text editor until you get a little bit of the hang of it. IDE's can do too much for you.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
I'd disagree with that, I think. Yes, an IDE does too much for you sometimes, but that's offset by having the debugger integrated into the dev environment - so "early stage developers" are more likely to find and hopefully use it. And debugging is hard when you get started, so anything that helps them to fix their code means they learn faster and better. We do learn a heck of a lot more from mistakes than successes! :-D
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony "Common sense is so rare these days, it should be classified as a super power" - Random T-shirt AntiTwitter: @DalekDave is now a follower!
-
I look at my app, and if something needs documenting, I figure it's probably too hard and should be rewritten. My documentation mostly consists of (control) tooltips. I used to create elaborate help files (using Help Workshop, etc) until someone decided to condense my help into a "guide" ... sort of like ketchup on one's filet mignon.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
Libraries like my graphics library pretty much demand documentation if anyone is going to use them. There are simply too many features to expect someone to find their way around by themselves. For example, my graphics lib supports 3 different types of fonts, each with different capabilities. I mean, The STL demands documentation simply for the breadth of it, never mind the complexity. I try to keep my code as simple to use as possible, and no simpler. Even in those cases, sometimes a project just demands documentation.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
-
I did say earlier that it's an unenviable task. It's such a chore. But, documenting my code forces me to review it. Just writing out how to use it uncovers areas for improvement. I've added several critical features to my UIX library as I've set about documenting it. I also shored up some function names that were out of step with my conventions. :)
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
I view documentation as absolutely essential and just part of doing a good job. If class and function names are genuinely sufficient, then that's fine, but if you try and ask yourself all the questions that a new user of your code might ask, frequently there's plenty to document for clarity. I'm quite lucky in that I have a lousy memory, so when I return to my code later, I may not be that far from a new user of it myself! I find myself thankful to myself for getting the necessary details explained and documented clearly! I think if a user of your code has to read any of the code in your function bodies, your documentation is insufficient. I also think it's also valuable if you can to spend some time writing code that consumes your code - essentially walking in somebody elses shoes. It can show you how easy or otherwise it is to work with, and can reveal opportunities to improve the design, or perhaps suggest function overloads you can provide simpler versions of to reduce any pain. If there's anything cumbersome or unintuitive about your code, you'll hopefully encounter it and be able to rectify it.
-
I a new person and coding it’s new and it difficult any tips .
It is worth having a look at the way the Git project writes it's Commit messages and it's documentation in terms of shifting from a subjective style of writing about what happened, to an objective imperative style. After a while of following along you start to see how you can stop apologising for what happened, and instead assert what is happening. We are taught (English 101) to write long waffle sentences, rather than short, concise and informative ones that we really need here. git/Documentation/SubmittingPatches at master · git/git · GitHub[^] The "Describe your changes well" section is a good start.
-
I look at my app, and if something needs documenting, I figure it's probably too hard and should be rewritten. My documentation mostly consists of (control) tooltips. I used to create elaborate help files (using Help Workshop, etc) until someone decided to condense my help into a "guide" ... sort of like ketchup on one's filet mignon.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
Gerry Schmitz wrote:
My documentation mostly consists of (control) tooltips.
Ooh, I really hate apps that assume that I will have the same mental model as the developer, especially when I don't ;). The expectations can easily lead into traps one can't get out of, and worse, ditching the app or tool. That said, it is really frustrating trying to explain something when you haven't established common ground from the start (the "your breakfast may be different from mine" problem). So at least having a purpose, concepts and usage approach documented will give users a clue as to where the code is going, especially if the app is 'special' (i.e. different to regular expectation).
-
Gerry Schmitz wrote:
My documentation mostly consists of (control) tooltips.
Ooh, I really hate apps that assume that I will have the same mental model as the developer, especially when I don't ;). The expectations can easily lead into traps one can't get out of, and worse, ditching the app or tool. That said, it is really frustrating trying to explain something when you haven't established common ground from the start (the "your breakfast may be different from mine" problem). So at least having a purpose, concepts and usage approach documented will give users a clue as to where the code is going, especially if the app is 'special' (i.e. different to regular expectation).
I never release an app I wouldn't use myself. I understand the concept of "flow". At the end of any project, I know more about the users' problem domain, than the user. Preaching to the choir.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
Libraries like my graphics library pretty much demand documentation if anyone is going to use them. There are simply too many features to expect someone to find their way around by themselves. For example, my graphics lib supports 3 different types of fonts, each with different capabilities. I mean, The STL demands documentation simply for the breadth of it, never mind the complexity. I try to keep my code as simple to use as possible, and no simpler. Even in those cases, sometimes a project just demands documentation.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
API's are different. I contrast "user" documentation and "system" documentation. And I use Visio for both. And Excel. And Word. Creating "internets". "Users" bother with none of the above. I create "user interfaces".
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
I had a University Professor who used to say "If you can articulate your problem, and narrate it to a friend, then the solution will strike to you in an intuitional flash". I feel that documentation is akin to this.
I once explained to a new boss how parameter passing works in a compiler we were doing. Midway through explaining, I noticed a bug, ran off to create a work item to fix.
-
does your code go through a Code Review process where you are not the one reviewing your code?
Review on my code is typically done by me, and as I’m trying to fall asleep. That’s when the “Oh bubblegum!” moment happens. :) :)
Time is the differentiation of eternity devised by man to measure the passage of human events. - Manly P. Hall Mark Just another cog in the wheel
-
I did say earlier that it's an unenviable task. It's such a chore. But, documenting my code forces me to review it. Just writing out how to use it uncovers areas for improvement. I've added several critical features to my UIX library as I've set about documenting it. I also shored up some function names that were out of step with my conventions. :)
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx
I started my embedded coding career in 1978. I was writing code for the Motorola 6800 by the op codes (we didn't have a 6800 assembler yet). Documentation was a definite requirement. I pretty much just automatically document my code since then. First, I know it's not necessarily me that's going to be taking care of the code, so I want it to be easy to understand my thought process.
-
And don't start with an IDE. Start with a basic text editor until you get a little bit of the hang of it. IDE's can do too much for you.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
-
I'd disagree with that, I think. Yes, an IDE does too much for you sometimes, but that's offset by having the debugger integrated into the dev environment - so "early stage developers" are more likely to find and hopefully use it. And debugging is hard when you get started, so anything that helps them to fix their code means they learn faster and better. We do learn a heck of a lot more from mistakes than successes! :-D
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony "Common sense is so rare these days, it should be classified as a super power" - Random T-shirt AntiTwitter: @DalekDave is now a follower!
Ok, I concede the use of a debugger. Point taken.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
-
Ok, I concede the use of a debugger. Point taken.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
Truly this is a week of miracles: today someone on the internet was swayed by logic :omg: and yesterday I saw a BMW driver use his indicators*! :wtf: These things never happen: what in in store for tomorrow? :laugh: * No, really. And correctly too. I was so surprised I assumed I was still asleep and dreaming.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony "Common sense is so rare these days, it should be classified as a super power" - Random T-shirt AntiTwitter: @DalekDave is now a follower!
-
And don't start with an IDE. Start with a basic text editor until you get a little bit of the hang of it. IDE's can do too much for you.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
Yeah, I disagree as well. I eschewed IDEs for most of my career favoring just plain vi--even on Windows--but since discovering Visual Studio Code, that all changed. With its VIM plugin, I can have the best of both worlds--a vi-like UI with all the VSC bells and whistles. For a complete newbie, an IDE can be a help and a hindrance. The sheer volume of options, settings, and plugins cam be a challenge and can quickly overwhelm a first timer. I'm like OP. My career is nearing a close. My first coding experience was also in 1986. The language was Exec2, and the hardware was an IBM System 370 mainframe. That was a different time. There were few tools available (Anyone here remember troff?), few language options, and no Internet to use for research. Now, starting out can be both easier and harder. Easier because there are so many more options to choose from and harder also because there are so many options to choose from. At least there are many great sources of information these days, but this is even problematic because _mis_information is just as common as the good stuff. Of course Kimmie needs to tell us a little bit more about what kind of programming they want to do. If unknown, my tip is to start with defining that. Cheers, Russ
-
Yeah, I disagree as well. I eschewed IDEs for most of my career favoring just plain vi--even on Windows--but since discovering Visual Studio Code, that all changed. With its VIM plugin, I can have the best of both worlds--a vi-like UI with all the VSC bells and whistles. For a complete newbie, an IDE can be a help and a hindrance. The sheer volume of options, settings, and plugins cam be a challenge and can quickly overwhelm a first timer. I'm like OP. My career is nearing a close. My first coding experience was also in 1986. The language was Exec2, and the hardware was an IBM System 370 mainframe. That was a different time. There were few tools available (Anyone here remember troff?), few language options, and no Internet to use for research. Now, starting out can be both easier and harder. Easier because there are so many more options to choose from and harder also because there are so many options to choose from. At least there are many great sources of information these days, but this is even problematic because _mis_information is just as common as the good stuff. Of course Kimmie needs to tell us a little bit more about what kind of programming they want to do. If unknown, my tip is to start with defining that. Cheers, Russ
I remember TRS-80 BASIC. TROFF and TRON to trace program execution. Now I use print statements to include variable values and don't output line numbers except before and after conditional branching. The old days weww so much simpler, but we didn't have enough RAM to work out bugs easily.
