True meaning of iterative development and refactoring code - php

Question

I have recently began working as a developer and working under a more senior developer who is kind of supervising / mentoring me.
A lot of things that he is advising just dont seem right though. For example, he tells me to just write my code in a procedural way ignoring how well its written or its overall design and just get it to work. Then iteratively it will get better as it needs to, improving the code over time.
This is making me uncomfortable about spending time actually properly thinking about the solutions and indeed the actual problems before coding and I feel that by rushing in and coding this way that in the end, more time will be spent on this. Unfortunately i am not at the stage of being able to solve problems immediately by writing perfect code first time.
Also,m he frowns upon documenting code, beliveing that it should speak for itself. He feels that a short comment at the top of each method should suffice. Again this seems counter intuitive to me.
All in all, i feel that i am now writing really hacky code in order to just get somehting up and running. Is he correct and is this the way things are done throughout the industry?

Answer 1

I'm gonna go out on a limb here and suggest that you might be misinterpreting what the senior dev is telling you. "Just make it work" and "code should speak for itself" are mutually exclusive. If we assume this guy does really know what he's doing, let me offer a couple of alternative explanations:
It's easy for new developers to get lost in the weeds agonizing over The Right Way to design software. It's a kind of Analysis Paralysis. He probably wants you to dive right into code quickly so that you actually get something written and you quickly discover what doesn't work well. It sounds like he's letting you fail early and often in order to learn.
A lot of new developers liberally sprinkle their code with useless comments. He's asking you to write self-documenting code, not hacky and confusing code. If you're only allowed a short comment at the top of a function, you have to use clear variable names and simple straightforward algorithms for the code to make sense. This is a Good Thing.
There's nothing wrong with sitting down with your mentor to clarify what he's telling you. You do have valid concerns. Don't hesitate to ask him for more information. It shows confidence and an ability to think for yourself. Good employees aren't mind-numbed robots.

Answer 2

No, that's not really how things are usually done. But there are some considerations.
There's a development pattern called "test-driven development". In this pattern, you basically write the least code possible in order to pass whatever tests you have. As the requirements change, you write new tests and then change the code to match. He could be angling you towards something more like this. In which case, if you write good enough tests, it doesn't matter what the original code looks like, if you tested for every case you needed to, then the code will always do what you want even if it is a horrible mess. (This is, by the way, why some people don't like test driven development).
On the subject of comments, of course comments are important. But comments are not a substitute for easily readable code, with properly named variables and function names. Over commenting is definitely possible and makes code harder to read and understand (because every other line is a comment like // increment i). Also, the more comments you have and the larger they are the more likely they are got become outdated and out of sync with the actual code. Everyone is going to read that and say "that won't happen" but it always does. Someone always comes in to change "on little thing" and doesn't update the comment, and then after that happens about three times the comment is just plain wrong.
There is one more thing to consider. Consider the possibility this person doesn't carry what he's told you as a philosophy, but rather he's just trying to help you. Maybe you've spent too long trying to properly design your solution before writing anything and he feels if you got something down on "paper" first it would be easier for you to improve it than trying to hold the whole solution in your head. Maybe you've been writing too many comments, bad comments, or spending too much time on comments (or even on comment formatting, I've seen this happen) and he feels you'd learned more at this stage by spending time on your code than on making pretty comments.

Answer 3

There are many schools of thought and many different styles. I have stopped counting and instead try to use a pragmatic approach.
In terms of implementing code I use the principle "make it work", "make it right", "make it fast". But then I also use "The simplest thing that could possibly work" (DTSTTCPW)
How much comments you write depends on a number of factors. One school of thought indeed advocates the thesis that good code is self-documenting. Also, I have seen endless comments that were completely out of sync with the code.
Another school of thought believes that you need comments.
I'm taking the position that there are several factors that influence your choice. One is your personal preference. Then there is your boss. In other cases there is your team. Ideally you would be all on the same page by jointly agreeing on coding standards. And in the end if you always have the choice: Love it, change it, or leave it. Choices 1 and 3 may be the only ones if your boss (or mentor) cannot be convinced or isn't willing to find consensus in the team.
My understanding of iterative development is that you add features in small increments. At any given time you are ready to ship and your code is as lean and mean as you can get it, including comments where appropriate.
My understanding of test-driven development (TDD) is that you use tests to drive the design of your system. This is more and beyond mere test-first programming.
This approach has worked for me for the last 10+ years and with many teams I have worked with. But I am sure that there are many other options, styles, preferences, methodologies that work equally well. It all depends!

Answer 4

Also, he frowns upon documenting code,
beliveing that it should speak for
itself.
That's pretty much all I needed to read. This person really has no clue about what it takes to write maintainable code.
With that said, this person is obviously your mentor/supervisor, so you can't just say, "hey, that's stupid", you have to do it tactfully.
But not documenting code because it "should speak for itself" is a recipe for disaster. And you should definitely pay attention to writing clear, effective and efficient code. It's always better to do something right than to just hack something together that you're not going to understand 6 months from now. If you don't understand it, chances are no one else will either.
I think you should talk to their supervisor and explain the situation.
With that said, there are sometimes reasons to take shortcuts if the timeline is tight, quoting Jamie Jawinski, who worked on Netscape,
"We're going to ship the
highest-quality product we can on
March 31st"
So you have to find the balance. But overall, writing helpful comments in code doesn't take that much more time, certainly not enough to significantly affect a project timeline, and I like what Donald Knuth said:
...when you write a program, think of
it primarily as a work of literature.
You're trying to write something that
human beings are going to read. Don't
think of it primarily as something a
computer is going to follow. The more
effective you are at making your
program readable, the more effective
it's going to be: You'll understand it
today, you'll understand it next week,
and your successors who are going to
maintain and modify it will understand
it.
In short, there's no substitute for writing highly effective, clear, and maintainable code, even with a tight timeline.

Answer 5

Its 100% opinion here, but if your solution is well designed I think a comment for each method can be the right amount. You should be describing what it does and why, but not going into the details of how. Unless your method is extremely long (indicative of poor design), the code should explain itself i.e. if your method looks convoluted and is hard to understand, perhaps you should break it down so that it reads more naturally. There are always exceptions, but thats my opinion.
Where I work, the code seems to have very few comments but if the method name is truly representative of its function, and the code inside the method is clean, I have no problems understanding it.
Unfortunately i am not at the stage of
being able to solve problems
immediately by writing perfect code
first time.
There is no such thing as a perfect code, its about knowing which comproises are acceptable.
Perhaps your metor is just trying to make your life easy by saying 'don't worry about the design'.
Or maybe he is referring to the practice of red, green, refactor (Test-Driven Development) - the idea that you should first write tests, then write the code to the point that it works - only then do you refactor it.

Answer 6

I agree on self-documenting code to a degree. You should name your variables and methods well rather than relying on comments. e.g. which would you prefer?
//Get the speed of the train from the database
int value = GetValue();
int trainSpeed = GetTrainSpeedFromDatabase();
What if I decided I wanted to get the trainspeed from an XML file now, in the second example I'm much more likely to update it so it makes sense and not leave the misleading comment.