Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
Over the years, I've discovered that green-programmers tend to read the comments rather than the code to debug issues.
Does having one person document the other person's code (and vice-versa) with the code writer's approval increase code quality in the long term?
Is this a good idea?
aside: I'm looking for middle-ground between solo programming and pair programming in terms of budgeting.
People tend to look for the easiest solution to a problem. If there's an "human" description available, it's likely to be utilized before the reader delves into esoteric code. IOW, the comments will often be considered first, regardless of how green the programmer happens to be.
Comments should maintained as well as possible. Unfortunately, they can easily become stale (because they cannot be validated by the compiler). Therefore, they should be kept to a reasonable minimum, because, ultimately, the code itself is the only real comment that can be trusted.
As for who should write the comments, it depends at what level the comments are being written. For example, at higher levels the comments should describe the outside behavior of a module, and could be written by a larger group of people. Internally, however, the comments should explain the intent of the various chunks of code. That way, its easier for the reader to glean the mannerisms of the code. Those comments should be written by the coder.
I've found that "pair programming" works best when one person writes the code and the other one writes unit tests (working side by side so they can see what each other is doing). You can swap the roles around occasionally too.
You run a higher risk of misinterpreting algorithms if the original author does not document the code. In my opinion, the only thing more frustrating than inadequately documented code is incorrectly documented code.
You may wish to try this approach:
Perform code reviews with a developer that was not involved in the programming effort.
Have the review performed without the physical presence of the code's author. Just the reviewer, a copy of the code from source control, and written documentation.
If the reviewer can not reasonably understand the code without outside assistance, it is not adequately documented and should be given back to the author.
Repeat as necessary.
I find it works best when the helper does the broad scope thinking (i.e. What are we trying to accomplish) and the keyboard cowboy does the detail scope thinking. I don't think comments have anything to do with it.
I tend to write comment first and code immediately after that or at times or at times side by side. By the time I end up writing my comment the code becomes very clear in my mind (thanx to the fact of verbalizing my ideas while writing the comment). I don't like to comment the code which I haven't written. And whenever I come back to revise the code, first read the original comments, then think of new comments, write them and write the code side by side.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
One of my tasks is to analyze source code. The chunks that usually takes the most time to be understood are those where the developer uses confusing terms for variables or methods, like...
myfavoritething=json.dumps(url) (what is this variable? what is the purpose? apparently the user is encoding the url for some dark purpose...)
public void getName(values, result) { ... (this was not a getter, the function has no return value, but it calculates a result from the input values)
POST /loadService (which does not load something, just returns a lot of variables)
Given that this is a quite common issue, is there a technical term for this coding-style bad habit?
Bad naming is considered to be a so called code smell. The term was first coined by Kent Beck.
In his book Refactoring: Improving the Design of Existing Code, Second Edition Martin Fowler describes patterns that help with refactoring specific flaws in code.
He also dedicates a chapter to code smells which are closely related to refactoring.
Getting back to your question:
Given that this is a quite common issue, is there a technical term for this coding-style bad habit?
As I consider this book as one of the top sources concerning this topic I would say the term that comes closest to what you are referring to is the Mysterious Name code smell as described in Fowlers book:
Mysterious Name
Puzzling over some text to understand what’s going on is a great thing if you’re reading a detective , but not when you’re reading code. We may fantasize about being International Men of Mystery, but our code needs to be mundane and clear. One of the most important parts of clear code is good names, so we put a lot of thought into naming functions, modules, variables, classes, so they clearly communicate what they do and how to use them.
Finding good names often is hard and if you are looking for some good advice in the right direction I recommend the book Clean Code by Uncle Bob. He dedicates a whole chapter (see Chapter 2 - Meaningful Names) to this topic.
There are few naming conventions to be followed by every developer to improve readability,maintainablity etc.
The above example given by you are called bad practice
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
In a big corp, they often ask developers to fill in a matrix of what skills they have at what level. It's generally seen as a bit of a pain but is it actually useful, or another way for bureaucrats to try and reduce developers to a bunch of numbers on a spreadsheet?
Skills matrix are only partially helpful, they are good at giving you a general picture of your current "experience".
However these skills matrix does not include the most important aspect, the ability to learn.
This is the most important skill in IT in my view. And everyone learns at different speeds.
Eg. Throwing guy A into a new technology stack, and how long before he/she is productive?
Since IT/software development is a very wide field I regard skill sheets as quite useful. I used to be a Linux expert and my skill sheet reflected that. Then I shifted into iOS/Mac development and my now-employer asked me to fill out a skill sheet tuned to Mac... and I immediately noticed that I was novice in this field back then ;-) Vice versa, they were able to see whether I can fit into the company and where (in which team).
So of course they can be harmful if you lack the skills, but I think they make choices for employers easier (and I regard a big skill sheet in my CV as the most important part of the CV, even more so than the list of projects done).
The usefulness is totally dependent on what is being assessed. I work in an insurance company and this was done for all staff here. There was no category that I fit into and all the criteria were irrelevant.
I can see the benefit of assessing relevant criteria, it can identify weaknesses and target training, but those criteria need to be defined by someone who knows what you might not know.
Most of all, don't berate the bureaucrat for simplifying a complex object into a manageable set of information. As a programmer that's what you should be doing every day.
I think it is appropiate on big corps, but for small and specialized consultancies I would make a personal interview.
In big corporations if you dont fit in one place you may fit in other... in small teams I rather do personal assessment .
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
When you are rapid prototyping for features should you really worry about code quality & optimization?.
Looking back at the number of times a "prototype" ended up becoming the product, the answer would be yes.
Don't forget that you are not only prototyping the feature, you are also prototyping the design.
Yes to quality. No to optimization. This question should be community wiki.
I would focus on clarity.
If quality and optimisation are requirements for the prototype then yes. If not, then no. Just because you are doing rapid prototyping you don't abandon standard operating procedures like programming to a specification, using source code control, testing, etc. It is, perhaps, relatively unusual for high performance to be a requirement for a rapidly developed prototype, but that's another matter.
Yes. Focus on quality, clarity and simplicity AND comments to explain what its doing and why (don't bother with the how, unless its really complicated, that is what the code is for).
Just about all work we do here starts out as a what if? And if it works we continue with it.
We write comments that describe what should happen, before we write the code, then write the code to match the comments. Writing the comments first forces you to think about how you will structure it all. We've found that it prevents a lot of FALSE assumptions and actually makes development faster.
It also makes reusing this when you come back to it so much easier - you don't need to read the code and understand it, just read the comments. Don't go for the nonesense of self-documenting code, all that does is self-document the bugs, you've got nothing to check to see if the code matches the comments/documentation at all.
You can worry about optimization later - see this description of a huge win I got by changing from MFC CMaps to STL when working on a hobby project parsing some Apache log files. This was done after I had the initial concept working and only when it became apparent there was a problem with performance.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
Robert C. Martin offers in the fist chapter of his book 'Clean Code' several definitions of 'clean code' from differen well known software experts. How do you define clean code?
Easy to understand.
Easy to modify.
Easy to test.
Works correctly (Kent Beck's suggestion - very right).
These are the things that are important to me.
Code I'm not afraid to modify.
Code that doesn't require any comments to be easily understood.
Code which reads as close to a human language as possible. I mean it on all the levels: from syntax used, naming convention and alignment all the way to algorithms used, quality of comments and complexity of distribution of code between modules.
Simplest example for naming convention:
if (filename.contains("blah"))
versus
if (S_OK == strFN.find(0, "blah"))
Part of it depends on the environment/APIs used, but most of it is of course the responsibility of the developer
Point-free Haskell code. (Not really, though.)
Code in which the different modules or classes have clearly defined contracts, is a good start.
Code which doesn't break in multiple places when you make a single, seemingly insignificant change. It is also easy to follow the control path of the program.
Reusable code is also important. So not only important is the quality of the code, but where do you put.
Example, business logic into a Controller is a useless code
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I'm working on a project that's been accepted as a proof of concept and is now on the schedule as an actual production project. I'm curious how others approach this transition.
I've heard from various sources that when a project starts as a proof of concept it's often a good idea to trash all of the code written during that rapidly-evolving phase and essentially to start over with a clean slate, relying on what you learned from the conceptual phase but without working to clean up the potentially messy code that you wrote the first time around. Kind of the programming version of "throw away the first copy of that angry email you're about to send and start all over" theory.
I've done it this was in the past and I've also refactored the conceptual code to use in production, but since I'm in the transition phase for a new project I wanted to get an idea how others do this. Obviously a lot depends on the project itself, and on the conceptual code (if what you generated works but won't scale for example, it's probably best to start afresh, but if you have a very compressed timeline for the project you might be forced to build on what you've already written).
That said, if all things were equal what would you all choose as an approach?
As you already kind of hinted at, the answer is, "It Depends"
Starting over is good because you can help trim out the stuff that was added while you were initially working out the kinks but isn't really needed.
It also gives you a chance to give more consideration to how you want the architecture to be -- without already being dependent on how the proof-of-concept was written...
In practice, though, unless you're in the business of selling the software to the outside world, building upon the prototype is pretty commonplace. Just don't get into the habit of thinking "I'll fix it later" if you run into some code that smells or seems like it could be done in a better way...
Refactor the existing code into the solution.
For me it would depend on how sloppy my POC was. If it is something I would be ashamed to pass onto another developer, I would rewrite it. Otherwise, just go with what you got.
If the code works, use it. Spend a little bit of time refactoring the messiest parts in order to ease future maintenance. But don't fall into the trap of building a new system from scratch.
Throw away everything from the proof of concept except for the lessons learned, and, possibly, some minor code fragments such as calculations etc.
Proof of concept applications should never be more than just the bare minimum to see if the technology in question will work and to start testing some of the boundary conditions.
Once done you are free to redesign the application with your new found knowledge.