|
Maybe it's cheating, and obviously this only works for personal projects, but I've found that submitting articles to codeproject is a fantastic way to document my code. It works for me because I enjoy writing, but I don't enjoy creating documentation, if that makes sense. I also think if i had to choose between a well written article that covered most of what I needed and a basic doxygen reference "documentation" based on code comments, I'd choose the former every time.
Furthermore, I've actually carried this over into some of my commercial projects (not using codeproject of course, but writing "articles" so that others can understand the code I wrote and it works pretty well if everyone is amicable to it)
Offered FWIW
Real programmers use butterflies
|
|
|
|
|
You are a very good article writer - on one of the digital streaming sites I use someone has just created a build to get a Logitech Media player on ESP32 devices
ANNOUNCE: Squeezelite-ESP32 (dedicated thread)
"Life should not be a journey to the grave with the intention of arriving safely in a pretty and well-preserved body, but rather to skid in broadside in a cloud of smoke, thoroughly used up, totally worn out, and loudly proclaiming “Wow! What a Ride!" - Hunter S Thompson - RIP
|
|
|
|
|
I think my problem is over-polish my code... Make it super-effective and super-readable at the same time, and never finish it...
"The only place where Success comes before Work is in the dictionary." Vidal Sassoon, 1928 - 2012
|
|
|
|
|
I've had some success with the "never finished" problem by implementing my own internal "code freezes" and thinking of my code in versions or phases. That way I don't ever have to "finish" it. I just create the next version, much like you'd do with an app. For me at least, this works because I don't feel like I have to get everything done on this version. I can decide "I'm going to freeze this version once it does X/looks like Y/is as fast as Z" and then I do it. And the things I want to do that I haven't done, I simply add to my TODOs for the next version.
Real programmers use butterflies
|
|
|
|
|
You mean there is code that is finished?  You surely must be joking.
My code is never finished because:
a. Just before finishing I found a better way to do it.
b. Customer added new requirements that need to be implemented.
c. Just had a new bright idea about something else to do (oh, my ADD is acting up again)
Kornfeld Eliyahu Peter wrote: I think my problem is over-polish my code...
That's a good line for the stupid interview question "What do you see as your weak points?" 
Mircea
|
|
|
|
|
Mircea Neacsu wrote: "What do you see as your weak points?"
I would answer that with 'sweets and snacks' 
"The only place where Success comes before Work is in the dictionary." Vidal Sassoon, 1928 - 2012
|
|
|
|
|
I struggle with the build process. Or rather, haven't even bothered to learn enough about it so that I can start porting my code to Linux. Maybe someday, or maybe someone will offer to set up the necessary build environment! But if anyone can recommend a good reference, I'd appreciate it. About 800 files, a dozen static libraries, and specific compile and link options are involved.
|
|
|
|
|
I'm assuming C++ here, forgive me:
I think it depends on the toolchain you want to use.
It might be best to start it on windows. Having a build environment that mirrors your linux environment on windows will make it easier to build for both platforms.
You can use this to accomplish it - usually: Mingw-w64[^]
That way you can use things like gcc and clang under windows.
I like to use VS Code because it scans for your compilers automatically, and integrates with things like CMake and make.
The biggest deal will be to get your code to compile for clang and gcc
after that you should be able to use the same tools on both systems, as long as you're using something like CMake
Real programmers use butterflies
|
|
|
|
|
Yes, it's C++. Is there anything else?!
Right now I just use VS2017 and configure it to do the build. I'd have to look into Mingw-w64. Is there a 32-bit version? I often build for that instead.
Being able to use gcc and clang under Windows would be a big plus. Then there's the question of debugging on Linux. Moving to VS Code once building and debugging works sounds like a good choice.
I did look into CMake, but all of these things look like arcana to me. A seasoned witch would feel at home with them, but I'd have a lot of learning to do.
|
|
|
|
|
Yes, there's both 32-bit and 64-bit versions as I recall.
Debugging on linux with VS Code is pretty easy since it integrates with GDB, the GNU C++ debugger on linux.
You can actually build your windows code from VS code as well, so it might be worth switching over entirely.
Real programmers use butterflies
|
|
|
|
|
Shoot. I just realized something about your post. You're talking about building for 32-bit. I believe you can do so with 64-bit minigw as I'm near certain the 64-bit build of the compilers and linkers can create 32-bit executables. You specify the architecture with some switch, i forget what as I've only used it once or twice. maybe -arch? I'd have to google it.
Anyway, it would be worth doing some legwork, and using the 64-bit minigw on a 64-bit system assuming you can. Then you run your build process for both on the same machine.
The only downside to using Minigw is you don't necessarily get access to the latest compilers.
I don't really like CMake, or make for that matter. I'm one of those people that feels like if you need a make file should have structured your source differently, *unless* you have code generation in place as part of the build process, or unless you want to run your tests as part of the build process, and honestly, I think a shell script is easier to use and understand. I don't really understand the point of make and cmake except to make your build scripts cross platform, but if you really want that you could just use powershell for it these days. Too many tools, too much nonsense. Not my circus, not my monkeys.
Real programmers use butterflies
|
|
|
|
|
I misunderstood mingw-w64 to mean that the tool targeted 64-bit, not that it was a 64-bit application itself, which was silly of me. It makes sense that it would have a switch for choosing the target.
When you say "code generation in place as part of the build process", I assume you mean automatic code generation in the original language as the initial step, not just regular object code generation.
|
|
|
|
|
Yeah, I mean source code generation, not object code generation, if I understood you correctly. Like some applications parse things, and they'll use a parser generator tool as part of the build process to create the source files for parsing whatever it is they need to parse.
Real programmers use butterflies
|
|
|
|
|
I need "white" space ... else it looks like rambling prose without paragraphs.
It was only in wine that he laid down no limit for himself, but he did not allow himself to be confused by it.
― Confucian Analects: Rules of Confucius about his food
|
|
|
|
|
Some functions just don’t break down easily either unless you want to pass a bunch of mutable objects around.
I remember one very complicated function that was a few hundred lines long. I could not find a good way to break it up any further. It used a lot of other functions for calculations, but the management aspects could not be refactored.
It was not hard to understand, but it was easy to lose your frame of reference.
I still have not implemented an equivalent function in JavaScript as the UI moved to HTML5. It was a proprietary layout algorithm that was fast and did the exact right layout every time.
|
|
|
|
|
Yeah I've had functions like that, where even if I wanted to break them up I couldn't. LALR(1) table generation tends to create long functions, or run into the problem of passing too many arguments, as you say.
But most of the time, it's a result of me attacking the problem as a whole unit rather than breaking it into parts. In my defense, there are some advantages to this, like whole algo optimization, wherein you can manipulate whole that would be much more difficult or impossible to do when working with the individual parts. It's hard to explain without being able to think of an example offhand, but when you run into it, you'll know. =)
Real programmers use butterflies
|
|
|
|
|
What I've mostly been struggling with during the past decade, was unmaintanable pile of spaghettig mixed with baclava I inherited. So breaking down things into maintainable single-responsibility modules kinda got hammered into my head.
What I struggle with instead, now that I get to build new generations of those systems from scratch, is the usual nerd tendency to overengineer things. "Hey, I just broke down this monster into maintainable modules, but I could break it down even further to serve even more different use cases".
I have to strongly discipline myself, using my conscious willpower to hammer YAGNI, KISS and similar into my brain. I'd say, getting that internalized so I don't have to remind myself is my next milestone.
Well, that and the usual: requirements changing, underspecified requirements with the not-so-techie product manager assuming I know what he means while not bothering telling me what he actually means.
|
|
|
|
|
I also have trouble remembering what I was doing in other modules. My solution is a little different from yours.
I keep a bound and page numbered notebook. In it, I record my thought processes as I break down a problem into solvable units. I repeat this decomposition until I have manageable units, each of which does one thing. At this point, I also plan my error and exception handling.
Then, I review the units. I group all the units that directly act on a given data structure into a single module. Typical entry points to these modules have names such as CreateInstance, DestroyInstance, GetPreviousInstance, GetNextInstance, SerializeInstance, DeSerializeInstance, one or more versions of FormatInstanceForPrinting, GetValueFromInstance, and PutValueIntoInstance, where "Instance" is the name of or shorthand for the given data structure.
All of the input/output routines are placed in one stream dependent module modules. One for the main window. Each subordinate window has their own module, with a separate business logic module. One module for the printer. One module for each file that needs to be read or written. One module for each database accessed.
Next, I review my previous libraries of code. Often, I have an existing module that I can directly use or use with a little rewriting. Some I have used so often, I have created a .dll for each.
Now, I begin writing code. Into the top of each module, I copy the design notes from my notebook into a comment block. First, the missing I/O routines. Then, the main window with its controls, followed by the subordinate windows with their controls. At this point, I can demonstrate the flow of control through the windows to the customer to get their feedback. Lastly, I write the business logic modules and tie the whole program together.
After a little "alpha testing," I ask the customer to provide some real users to do some "beta testing." When the customer is happy, the code is done.
Having the comment blocks in each module refreshes my memory and provides a notebook number and page number to look up my thinking when I wrote the code. This really simplifies code maintenance.
The notebook not only documents my design, but also the problems I encountered and the dead ends I reached while designing the program. It also records where I was at the end of the day or when I have to put the project aside for some dumb meeting or a higher priority task.
__________________
Lord, grant me the serenity to accept that there are some things I just can’t keep up with, the determination to keep up with the things I must keep up with, and the wisdom to find a good RSS feed from someone who keeps up with what I’d like to, but just don’t have the damn bandwidth to handle right now.
© 2009, Rex Hammock
|
|
|
|
|
That works for bizdev, but not so much with IoT and embedded where you can't usually afford much abstraction and every byte of memory matters. When you're dealing with 2kB-4kB of RAM at 8MhZ and 256kB program space you forgo a lot of the things you take for granted in business software.
Real programmers use butterflies
|
|
|
|
|
I agree. I "cut my teeth" writing embedded code for DOD avionics computers and FAA radar systems. It had to be written in assembly language because the compilers of the day (1970s) were horribly inefficient and the "optimizers" were buggy. Everything had to be documented to DOD specifications and data item descriptions (DIDs). Thankfully, the source code, however, did not get loaded into ROM. The source code was printed, bound, and included in the documentation, along with a punched paper tape or punched card deck for the source and paper tape for the binary. Only the binary was programmed into the ROM chips - the largest avionics system I worked with in those days had a whopping 12K of ROM for the program and 4K of RAM for data.
When I moved to the commercial world, I programmed Intel 8008, 8080 and 8086 and Motorola 6800-class processors. (PS: I preferred the flexibility of the instruction set of Motorola processors over the Intel processors.)
Later, I moved on to minicomputers (remember them??), UNIX, C and finally to Intel 80x86-based "personal computers" running Windows 3 and 3.1 on top of DOS.
__________________
Lord, grant me the serenity to accept that there are some things I just can’t keep up with, the determination to keep up with the things I must keep up with, and the wisdom to find a good RSS feed from someone who keeps up with what I’d like to, but just don’t have the damn bandwidth to handle right now.
© 2009, Rex Hammock
modified 3-Dec-21 2:42am.
|
|
|
|
|
I struggle with people who don't know what the word "omphaloskepsis" means
«The mind is not a vessel to be filled but a fire to be kindled» Plutarch
|
|
|
|
|
I struggle with style as it pertains to the coding of others. I can best understand a function by collapsing it into its primary logic gates, so when others fail to tab nest, the collapse is ugly at best and non-functional at worst. If these others would also add appropriate comments, I wouldn't mind as much, but it seems that not leaving notes goes with not nesting. I find that frustrating.
Also along the lines of style, I like to see standardization throughout in things like error handling, security, and naming conventions. I don't care so much which method you choose, but stick to one for the sake of others who come behind you.
BTW I don't bother trying to remember my function calls and parameters, I just copy/paste. I ctl-f, ctl-c, ctl-v all day every day, plus split screen editors. Tools, baby! I love 'em.
|
|
|
|
|
Documentation for end users. Currently reworking a 1000 page manual covering a variety of related programs. I hope I finish it next year. 
|
|
|
|
|
I'm fairly dyslexic, gets much worse when I'm tired or too stressed. especially verbal to writing or reading out loud, it all gets jumbled up. sequences of more than 4 numbers I can't remember. As a result, I don't trust my memory.
So like you I don't like to spread my code all over the place, but I will still breakdown issues into smaller chucks, usually in the same file, so it's just a scrolling issue. if it's across multiple files then splitting the screen is an absolute must.
Since I don't have confidence in what was written, I test early and often whenever I can. but that also means I have way less issues in production than a lot of my peers. I also document my code, and when the language supports it add signature docs to each function, so when typing out code to connect to other code, the IDE will help me remember what params to pass or other relevant information.
My biggest issues are usually switching between languages and remembering how to do something when two different languages do things similar, but not quite. so C, C#, Java, JavaScript, Rust, D, kind of blur together event though not the same. Had the same issues with ADA, Basic, and SQL oddly enough.
|
|
|
|
|
Quote: you'd think I'd be better at making it accessible to other developers.
Maybe hand out copies of this with your source: How to Quickly Understand the Code of a Function - Fluent C++ 
Cheers,
Mike Fidler
"I intend to live forever - so far, so good." Steven Wright
"I almost had a psychic girlfriend but she left me before we met." Also Steven Wright
"I'm addicted to placebos. I could quit, but it wouldn't matter." Steven Wright yet again.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
