|
Sorry, but it doesn't matter if it is "professionally" or "your own".
I know it is a very popular view these days, but I learned to document first, before even writing a single line of code. And that includes having (insisting! when it comes from an outside request) the specifications for a project.
And then, and only then, start "coding", according to the existing specs and docs. And if you do this, properly, without using shortcuts, this will drastically cut down on any debugging/testing/troubleshooting afterwards.
If you don't do this, you are just a code monkey, hacking away at a keyboard and you will always run into problems, no matter what the project is. And that "running into problems" is the real part that takes away any fun and satisfaction on this kind of job. It is NOT the documentation. And no, the documentation is NOT in the code, not by a long shot...
|
|
|
|
|
None of that has anything to do with liking it or not.
I spend plenty of time on documentation.[^]
It doesn't mean I enjoy it, and I don't mind saying so.
I should add: Furthermore, everyone's got their own opinion on how things must be done, will argue it 'til they're blue in the face, and everyone that does things differently is a "code monkey". I'm too old for that nonsense. When I start reading it, my eyes glaze over. I developed a process and order that works for *me* and allows me to produce solid, maintainable work. And it does work. I'm paid quite well, and my clients are happy with what I produce. At the end of the day, that's what matters, not how I got there.
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
modified 28-Aug-23 12:57pm.
|
|
|
|
|
In an ideal world, I should get a specification which fully documents what something is needed to do. I write it and send it back having tested as far as I can, then the business does extensive tests and the bugs get corrected before it gets released.
So we should only need to code and test to the requirements and then the specification is the documentation.
As I said, "In an ideal world, ...". 
|
|
|
|
|
StarNamer@work wrote: ...and then the specification is the documentation.
As I said, "In an ideal world, ..."
Well, I have issues with that on two counts:
- the specification only provides the "black box" description of the code, what gets in and what gets out. It doesn't say how to do it. It is up to you, the programmer to choose/devise the best algorithm, data structures to be used, limitations and compromises you had to make and so on; in brief, the nitty-gritty of the implementation.
- as you say, the world is not ideal and specifications are not complete so you have to make decisions during the implementation on how to solve those blank spots in the specification. You do it either by going back to the user, or by making informed choices but in the end all that accumulated knowledge has to be put somewhere by someone and I'd argue that you are in the best position to amend that specification and transform it into a manual.
Of course things can be different if you are part of a humongous organization and you are just a little cog doing your little bit for an enormous project. In that case there are probably many other people doing documentation, testing, integration, etc. and you just have to do (well) your bit of coding. However the OP was talking of design and contrasting it with documentation and testing, often seen as "lowly" activities. My point was that, in smaller projects, where you have certain freedom to design and implement stuff, there are no "lowly" tasks and everything has to be regarded as equally important.
I could go on, but I already feel that I'm ranting. Sorry...
Mircea
|
|
|
|
|
What I now do probably falls under your classification as:
Mircea Neacsu wrote: part of a humongous organization and you are just a little cog doing your little bit for an enormous project
Most of our business users are quite happy specifying UI changes, notifying legal requirements and otherwise just treating the whole distributed setup as a "black box". The IT team keeps track of how everything really works!
I'd question describing my role as "a little cog" since it's more a case that I get the issues no-one else has managed to solve. I do more support and fixing than actual development these days but have probably worked on all areas of our main in-house application.
However, the "humongous organization" is probably correct as the company was blocked from an acquisition a few years ago as it would have had too much market share in the UK; my boss used to describe it at trade fairs as "the largest UK company you've never heard of"!
|
|
|
|
|
StarNamer@work wrote: I'd question describing my role as "a little cog"
I didn't mean that disparagingly. Little cogs doing their work well in a humongous organization put the man on the moon. In my book, they are all heroes. And, yes, some of them were programmers[^].
Mircea
|
|
|
|
|
Ditto Mircea, I agree.
In my grad school computer lab, we had the proverbial toilet paper picture with "The job's not finished until the paperwork is done!", on the wall next to our Data General Eclipse mini-computer. Our mentor/professor meant it as we got graded from A-to-Z in preparation for the professional world of computer programming.
"A little time, a little trouble, your better day"
Badfinger
|
|
|
|
|
Mircea Neacsu wrote: I don't think your question has a proper answer between professionals
So you like everything about your job?
Including the meetings with management?
Very few people like everything about their job.
In fact, not many people really like their job at all.
As for the rest of your post, I come across very little code that's properly documented, my own code included.
I don't find it all that important and neither does my customer and it's never been an issue.
Same goes for automated tests.
The greatest bottleneck in my code is a piece that requires extensive UI and integration testing (of which a part can't even be tested because third party).
It's faster and easier to just manually run the code a few times and get that code in order so there's fewer chances of it breaking.
Having said that, I hate writing documentation because the moment you write it the software will have evolved and the documentation is outdated and no one will ever read it anyway and for that reason I never trust documentation.
I also really dislike writing tests.
The only tests I've seen never broke until they did because functionality changed.
Never have I prevented a bug with tests.
I use tests when writing complicated and easy to test logic, like parsers (but I rarely write those and when I do they're simple parsers).
|
|
|
|
|
Sander Rossel wrote: So you like everything about your job?
Including the meetings with management?
Yes, I lived an enchanted life  My boss for 20+ years was the owner of the company, an intelligent, nice person who called meetings only when needed and kept them short and to the object. Otherwise, I had my share of delayed flights, lost luggage, running into the occasional idiot, in short the usual unpleasantness of life, but that's not something I could blame on my profession.
Sander Rossel wrote: In fact, not many people really like their job at all.
I know. In fact I see it as one of the best paths to a miserable life. Hopefully, most programmers who hang out in their spare time at a coding site, do enjoy their profession. Otherwise I'm very, very sorry for them.
Now about documentation:
Sander Rossel wrote: I don't find it all that important and neither does my customer and it's never been an issue.
Really? I imagine you provide your customer with some type of manual or instructions. As for documenting the internals of your program, if other colleagues need to look at your code, I'm not sure they enjoy the experience. If you are a team of one, it might not be that important in your younger years or if you are writing throw-away code that is used only once and never revisited. If you are writing reusable code, docs matter.
Sander Rossel wrote: I also really dislike writing tests.
The only tests I've seen never broke until they did because functionality changed.
Never have I prevented a bug with tests.
I don't know what type of code you are writing. It might be your case, but in my world tests do matter. I do complicated math stuff and I want to make sure it works for all acceptable inputs.
Some of the code I wrote has been in use for 10-15 years and that's because of a combination of being well-documented and properly tested.
Mircea
|
|
|
|
|
Mircea Neacsu wrote: but that's not something I could blame on my profession
Part of the job, I guess.Mircea Neacsu wrote: Hopefully, most programmers who hang out in their spare time at a coding site, do enjoy their profession.
I do Mircea Neacsu wrote: Really? I imagine you provide your customer with some type of manual or instructions.
None whatsoever.
My code is custom made for every customer so they know exactly what they're getting.
I get an occassional call like "Sander, if I press this button will it do x or y?", but that happens maybe once a year.
Mostly because all buttons are pressed on a weekly basis so people know what they do.
I've written plenty of manuals in the past and I think none of them were ever read.
Even with a manual, it's easier for my customer to call me than it is to find and read the documentation.
At one time the customer even requested a help menu, accessible from an "info-button" at the top right of the form.
We documented the entire form and added the button.
The only one who pressed it was me when they called "what does this do?" 
One time a customer told me "I didn't know what to expect, but I opened it and I just knew where to go because the software is so intuitive."Mircea Neacsu wrote: if other colleagues need to look at your code, I'm not sure they enjoy the experience.
I recently got a new junior employee and he had little trouble working through my code.
It's not that hard either, you POST a form and end up in the OnPost method and you can figure it out from there.
A few if-statements, a for-loop, some validations, save something to the database... Nothing too complicated.
I have the advantage that most of my code has a GUI, which means most of the funtionality has a visible component, which also makes debugging a bit easier (there's always a clear entry point, like a button click).
Some of my code is a hassle to work with, but I wouldn't even know how to begin to describe it.
Just set a breakpoint and walk through the code line by line, I guess.
That's really the only sure way to know what code does.
Reversed, I never read documentation either.
If I have to read lots of documentation just to understand what's going on, it's probably bad code and the documentation would be just as bad.
On that note, writing good documentation is a skill in and of its own and few people know how to do it well.
I sometimes make a diagram when I have more than a few applications that make up a product.Mircea Neacsu wrote: I don't know what type of code you are writing. It might be your case, but in my world tests do matter. I do complicated math stuff and I want to make sure it works for all acceptable inputs.
Mostly LOB applications.
I really don't need to test that a button click results in some entity being validated and saved to the database.
I manually tested it and it works.
Every update probably works too, unless you're a huge nitwit who not only broke simple existing code (which usually means deleting it), but also didn't test it.
Let's put it this way, I've worked on such applications for 14 years and it broke maybe once or twice (not to say I don't have issues in production, I do, but rarely something a unit test would catch).
On top of that, I've seen such badly unit tested code (like unit tests that asserted an exception was being thrown because a class wasn't properly constructed in unit tests!) that I've come to believe most people simply don't understand testing, like writing documentation, and ultimately ends up being a lot of wasted time.
Don't even get me started on coverage!
Having a minimum test coverage is like saying programmers should write x lines of code a day.
That's not to say I dismiss all unit testing and that I've never applied it myself, but all in all, it's mostly not worth it for me (I do have a few unit tested classes).
Seriously, I don't get the fuss about documentation and unit testing (or commenting code for that matter, which has all the same problems documentation has, but it's even harder).
I think it's applicable to only specific branches/use cases, like your math-heavy applications.
Someone, sometime, decided that documenting/unit testing was a best practice and everyone just went along with it (just like scrum  ).
Mircea Neacsu wrote: Some of the code I wrote has been in use for 10-15 years and that's because of a combination of being well-documented and properly tested.
I know some bad programmers who don't even know what unit testing is and who don't document a thing, and their code's been running for 20-30 years (yes, still VB6, sometimes even with a dBase database).
Those applications were recently ported to .NET 2.0 (because the programmer didn't know any better) and SQL Server.
Somehow that's possible even without documenting and unit testing (or proper programming knowledge)!
|
|
|
|
|
Sander Rossel wrote: Part of the job, I guess.
Price to be paid for travelling to 50+ countries on 6 continents with all travel expenses paid 
Sander Rossel wrote: Mostly LOB applications.
I really don't need to test that a button click results in some entity being validated and saved to the database.
I manually tested it and it works.
There is some difference in purpose and scale. In my case, the same software was/is used for data acquisition and visualization by over 5000 customers who connected 200+ types of devices. Besides, operating costs for some of the customers were so big that a single day lost was more than the cost of our software. If it wouldn't have worked, they would have thrown it overboard and I wouldn't have had the chance of a comfy retirement. 
Mircea
|
|
|
|
|
Mircea Neacsu wrote: travelling to 50+ countries on 6 continents
I'd absolutely hate that part of the job 
I hate visiting customers, save for two are even closer than my own office (6 and 7 km vs. 14 km).
I don't like working from home all the time either though, need to get out and socialize once in a while 
Mircea Neacsu wrote: There is some difference in purpose and scale
That's my point exactly.
In your original post you said: "The oft repeated lament "I hate documenting/commenting" is driving me nuts: what good is your work if you cannot explain to someone how to use it or if you explain it badly? Saying that you don't want to cover with tests all significant cases is like someone performing a CAT scan and stopping in the middle: probably the other half is also OK."
However, at my scale, it adds more work and complexity than it takes away.
Just like almost everything, whether you need documentation and unit tests "depends" on your use case.
Not having proper build and release pipelines is leaving the job half-done though 
|
|
|
|
|
Sander Rossel wrote: 'd absolutely hate that part of the job
I hate visiting customers, save for two are even closer than my own office (6 and 7 km vs. 14 km).
To each his own: me, I love(d) travelling. Now my bucket list is empty. I still like vacationing but it's not the same as when you go for work and get a chance to know people and see their real life. I guess I'm more of a traveler than a tourist.
Sander Rossel wrote: Not having proper build and release pipelines is leaving the job half-done though
Amen!
Mircea
|
|
|
|
|
There's a marked difference between not enjoying something and not doing it. Mind the gap.
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
|
|
|
|
|
Documentation, as I am no good at writing clear instructions. Testing comes a close second, as I get bored after a few iterations.
|
|
|
|
|
Quote: Documentation, as I am no good at writing clear instructions
Now appart from Q/A where you simply reply with a link, I have a strong feeling, that you are writing very good instructions 
|
|
|
|
|
The quality of my answers does depend also on my mood.
|
|
|
|
|
Why it just happened yesterday...
I spent 5 hours trying to fix a 'bug' where setting a chart series point to IsEmpty was not reversible and led to completely bizarre results. (works the first time, not the second) Found that IsEmpty for that object was the same as Double.NaN. Try using that and .NET complains that it can't handle NaN!  (again, works the first time, not the second)
This morning, try it again and it works perfectly!  I love/hate it when problems just fix themselves! Hmmm...the only difference was VS2019 yesterday vs. VS2017 today???
Edit: It still doesn't work! I just didn't test correctly! More research indicates that it's a known issue albeit an apparently rare one. At least they provided a workaround...only it doesn't seem to work either. (clearing the points and adding dynamically) Back to the drawing board! 
Really though, my least favorite part has got to be communicating with colleagues. It's all too normal anymore for me to be stuck on a 1-2 hour phone call when I'd rather be fixing things! Also, there's communicating with family during working hours, which also happens way too often these days.
It's hard to be antisocial when every 10 minutes there's a phone call, text message, notification, email, etc. though I still try!
"Go forth into the source" - Neal Morse
"Hope is contagious"
modified 27-Aug-23 17:08pm.
|
|
|
|
|
Anything with dependencies you can't resolve yourself. Trying to communicate with a peace of hardware and asking for documentation on how to connect to a standard protocol: "we will get that to you next week". WTF. That thing cost 1 million euro, and we have a good handful of those.
Besides that, CI/CD pipeline. Is as such simple enough, but always end up tedious and eating a bunch of time.
|
|
|
|
|
Sometimes I like that challenge. Other times it can be frustrating.
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
|
|
|
|
|
It can be a challenge when you have access to something you can examine. In this specific case, all we have access to is a 404 response if we do not guess the URL and port.
Another problem with 1 million euro gizmos, they do not give us any to play with in a test environment.
|
|
|
|
|
If the "user" won't help with testing, I start losing enthusiasm fast. That said, I have lots of "eyes" into my software's internals.
"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
|
|
|
|
|
Yeah. I have two people I know are using my graphics library seriously, one guy who is using it has been an invaluable resource, not only uncovering bugs, but tracking down where they are in my code and even suggesting fixes. I offered a collaborative role on the project with him, that's how much he impressed me, but he's of course otherwise occupied. Still, I'm glad to have him using my stuff!
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
|
|
|
|
|
Quote: What's your least favorite part of coding?
Coding.
Yeah, I'm burnt out at the moment; have been for 6 months or so. Ugh. Extensive overuse of tight deadlines usually causes this for me.
|
|
|
|
|
I hear that. I got burnt out due to lack of challenge and lack of creativity, coupled with long hours. I can handle eating and breathing code but not always on another person's agenda, and not if it's the same stuff over and over again. How many different ways can you design an e-commerce app? It makes it somehow worse when other people are actually excited about it.
I left the field for years.
I got scouted off codeproject actually. That's what dragged me back in. I'm enjoying IoT and embedded because it reminds me of the same type of problems I faced coding in the 1980s and early '90s. The idea is to get little things to do big things, and solve problems on a limited medium. It brings the challenge and creativity back for me, like getting TrueType running on a system with 192kB of RAM or less.
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
