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 1 year ago.
Improve this question
I am a junior software engineer at a company in the USA. And as many as you engineers know, many times I run into heavily undocumented code, with little to no/zero comments (I mostly code in Java).
Now, I know you might say the logical response of "well, comment the code then dude!", which I have done before, but something I have noticed is that the entire codebase is uncommented, so it looks "weird" having a few commented methods and such out of the blue. It would probably take many more hours or sometimes I simply lack the information on the "grand" scale of how the application or system operates, so I would not be able to comment the entire codebase or functionality.
I wanted to ask you fellow software engineers who also have uncommented/undocumented legacy applications and work in industry if:
I should be fixing and commenting the entire codebase when I work on defects/bugs and new features
Leave it alone since its a legacy application and follow the pattern that was set before (no comments)
Comment individual pieces as I work on the application over time
Are simple comments like // this is a comment preferred or java-doc style comments? (below):
/**
*
* #param the four byte rgb pixel value from image
* #return the bitwise AND of the rgb value and a bitmask
*/
Thank you!
The fact is, there is no "right" answer to this question. The first question I would ask is: does your company or team have agreed upon development practices? If so, commenting practices should at least have a passing mention in there. There are some people who believe well-written code is self-explanatory and needs no comments. This could be the case there. It could also be the case that they believe that but their code is not self-explanatory - that would be a different conversation. Not having an agreement in the team or department will make anything you try to do a losing battle.
To your specific questions:
No. If you have a whole code base that is not documented or commented and you take that on without direction or approval, you are committing an astronomical amount of time and money to something that no one asked for. At the least you will make people upset with you. At worst, I've seen people fired for this kind of thing.
This is probably an equally unhelpful extreme. It doesn't have to be all or nothing and this doesn't improve the code base or really contribute anything positive and you'll probably just frustrate yourself.
This probably makes the most sense, but I stress again, talk to your team about agreed practices. Maybe suggest in a retro (since you have a scrum tag) that there is time put into each backlog item to do this for affected code. I bet you aren't the only person who thinks this way.
Some teams like one, some teams like another. Talk to people, but in the end, it probably doesn't matter. The main difference I've seen in all my years of programming is poorly done inline comments can get lost and with poorly done block comments, you can lose pieces of code. Doing either badly makes it harder to follow. Doing either well makes it easier.
You've got a good answer already, but I wanted to add a bit about JavaDoc.
The value from JavaDoc comes from the auto-generated documentation. This is particularly useful when documenting something like an API.
You would get less value from partially JavaDoc coverage in the code. For example, a JavaDoc that only covers half of an API would be way less valuable than one that covers it all.
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 3 years ago.
Improve this question
... and how to prove to management that use-cases can be informal and still useful?
Hi folks,
I came in the middle of a project and found out that there are no use-cases, user-stories, requirements, neither anything similar to a specification. Since the deadlines are short, the current dev team don't want to spend time on such things. I wanted to join that project, but by digging more I found out that the current development adds features just by considering their "wow-effect" and chooses what to add just by using the easiness that the underlying technology provides. I was surprised how they have managed to go so far (more than 4 months) without requirements, but this is what we have now. I believe that the way they have chosen is the most sure one to kill the product which has a good marketing value.
Am I right, and what would you do in a similar circumstances to prove the dev team/management to make use-cases/requirements before moving forward? Thanks in advance, kh.
P.S. Two copies of Cockburn's book are on the bookshelf...
You should give your colleagues the use-case spiel :D Tell them that use-cases are useful as they're:
A way of capturing business processes in a manner which is reasonably comprehensible by all stakeholders. This helps to bridge the gap between programmers, clients and users.
Traceable units of functionality. Use-cases are formed (ideally) in the analysis phase, referenced in the design phase, and can be used as sources for test cases later on.
Quick and easy to write up and useful, even if informal.
If you need more ammunition, you might want to read Use cases - Yesterday, today and tomorrow by none other than Ivar Jacobson.
If your colleagues still can't see the potential usefulness of use cases as a business analysis tool, then they're probably beyond help :P You should remind them that they're developing software to meet other people's needs and solve their problems in the long term, not to ostentatiously impress them in the short term with petty gimmicks. And so a little bit of direction and specification helps. Even if the use-cases themselves don't prove to be that useful, the simple act of coming up with them will force your colleagues to consider the actual underlying purpose of the software.
Ask questions, of both sides. Of development, ask them if they are certain that all of the ways in which they have considered using the application are all of the ways in which the end-users will want to use it; if they say they have, ask for proof. Of management, ask if they've ever used software that does everything they want, but still ends up being hard to use (they will have). These questions will seed the concept that what will be delivered might not be what is desired, on both sides; use that seed of an idea, then, to open up discussions (not documents, not at the start) on how the software will be used, and in what way any differences can be resolved. They'll get around to use-case documents eventually.
I am a product manager by profession, and my first reaction to your post is that ideas can come from anywhere, and if the dev team has decent ideas they should be incorporated into the product.
Having said that, a product can not develop a soul (a simple message) through a string of disconnected ideas that do not serve the ultimate purpose: solving the needs of a target user. And, ultimately it boils down to making the case that time is better spent on requirements/use cases that make sense for the product, while the opportunity cost of not having a clear strategy/end goal will lead to too many chefs and a jaded product message.
The ultimate way to make this message hit home is to involve other stake holders and have development demonstrate their work. Eventually, there will be disagreement and a more formalized (less cowboy) approach will lead to a more refined and simple product.
One of the problems you mention is tight schedule and scope creep induced by the devs themselves. Explain them, that by using use cases you can earn time by dropping features, which will potentially end up on the "never used" pile. With use cases you can find out what are the features customers need and will pay for and by removing unimportant features out of the scope you would have time to implement. Use cases apart from defining the scope also help to identify all the stakeholders, which might help you to focus even better while defining the scope and prevent forgetting about trivial things, which are not so apparent, but are a must if the product should be usable. The third most important thing about use cases is that they allow you to start thinking about corner cases which might be important for the customer before development and therefore you can find out with the customer what would be the ideal solution instead of letting the coder decide on his/her own under pressure of deadline.
Just show them.
Example is not the best way of educating people, it is the only one.
Lead by example focusing on extensions and exceptions. In other words emphasize the failure scenarios because everyone knows how the system should work. The real value of written Use Cases is identifying what should happen when something goes wrong.
That noted, consider you may have to live without written use cases. And, for the environment you describe, a major win is any sort of requirements documentation. Screen comps and/or prototyping are often easier to introduce.
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 know this may not be exactly a coder question, but I feel it is still related to programming because I'm sure many developers have come across this before and might have some insight on how to resolve this or have advice. There is an actually programming question though.
My issue as a developer.
I work in a small company, roughly 15 people, 5 of which are developers include myself, the rest are tech support and management. Problem I'm having is, when we get a SOW (Statement of Work), our clients give us a rough description of the project they are requesting, which usually is a 1-3 page brief description, usually including a Visio document, now as a programming, I'm responsible for going over the document and relaying a time-line on how long it should take me to complete the project.
Unfortunately, there have been times, not only me, where we under-estimate the project because we didn't fully get into it till we actually developed it, which ends up slapping ourselves in the face, because my boss is upset because he is being hounded by the client, who is now upset because we missed our promised deadline.
My question is, how do you guys handle organizing basic project description when you need to give deadlines on more concept, and do you have any ideas on how to organize it.
I'm thinking of going to my boss and suggesting, instead of always pushing a estimated deadline to our clients which expect us to hit that, we should write up a detailed document that is more step-by-step (more like what to do) on how to develop the application they want, it may take a lot more time, but least if the project is moved to someone else it is laid out for them, and when I usually get back to it 4 months later, I don't have to refresh up again, I can just follow the steps I wrote.
What do you guys think? Ideas? Or better ways to handle this?
If you switch your development to using an iterative methodology (Agile, XP, Scrum, etc), then the customer will see results much earlier than any deadline you feel you have to promise - usually every 1 or 2 weeks.
The moment they see what you've developed, I can pretty much guarantee that they'll make changes to their initial requirements as they now have a visual representation of the product and it may not be quite what they were thinking of. Some of their changes might be quite radical, so best to get the feedback as early as possible.
In all the projects where i've insisted we do this, the customer was delighted - they saw the results early, could influence the project outcome, and we hit their end deadline. Unexpectedly, a whole load of features got left behind and - guess what - the customer did not mind at all as they got the top features they wanted and put the project/product straight into production as they'd had lots of time to refine it to suit their business, so they were already familiar with it.
It takes a lot of effort to get management, sales, creative, etc, to all buy-in to an iterative style, so you may need to implement a hybrid solution int he mean time, but in my experience, it is well worth it.
If a complete shift to iterative is not possible, split your project into tangible milestones and deliver on those milestones. As others have said, inflate your estimates. My previous manager doubled my estimates and the sales team doubled his too.
Inflate your project deadlines. It's something that most programmers should do (and I quote the VP of Freeverse, the company that I work at):
It is a well-known fact among people
who work in the software industry that
the last 5% of development always takes the longest.
If possible try to divide the higher level tasks as much as possible so that you can get a better approximation of how many man hours that sub-task would take.
Also, adding hidden buffers to your task execution helps in covering some of the unseen contingencies.
cheers
If you mock up (balsamiq or whatever) with your customer, you will get more details. Armed with those details and some experience, your estimates will be more accurate. And then double it and add 4 (hours,days,weeks,months)
First, unless you systematically under-estimate, your boss should not get upset. It's his job to answer to the client, and he should know that by definition, an estimate is NOT the future. Statistically, sometimes you should deliver earlier, sometimes later.
Personally, I think that the frame of "how long will it take" is not exactly the right discussion to have. Software development is a risky business, and change/surprises happen all the time. One approach which helps is to focus less on the "right" number, and more on the volatility. Look at the project, and consider the places where you are pretty clear on how long it will take (you have done it before and understand it well), and look at the places where you have uncertainty (unclear requirements, new technology), and for these, think about how bad it could go, and why. That will help you get not one number, but rather boundaries: what you think is reasonable, a worst-case scenario, maybe a best case scenario (which the client should never see :) ) - and convey that information to your boss, so that he can manage accordingly.
Additionally, this will allow you to identify the danger points of the project, and you can then prototype accordingly - look into the uncertainty points as early as possible, so that you can tighten up the timeline fast, and have early warnings for your boss and the client.
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 have worked on a few multi-cultural projects (programming languages are universal, social norms and mores are not) and it's always interesting to see how the team dynamic works cross culturally. I'm not talking about coding differences, I'm talking about basic ground rules for communicating cross culturally at the start of the project. Good team building exercises, using small teams vs large teams, isolating functionality to make all developers feel as if they are contributing, fostering respect, and etc.
In our increasingly multi-cultural industry, what works and what has failed?
I looked into this in some detail a few years ago and came to the following conclusions (in no particular order):
The outsourcing organisations we looked at (all Indian) had a very strong process base. I don't know if this was cultural or just the way they chose to set themselves up (possibly a bit of both) but we felt this was likely to be a real issue.
They were talking about being a five on the Carnegie Melon Maturity Model (Google it but basically that means they've defined and documented everything up to and including what happens when someone farts), we were typically running around a 1 or a 2 (roughly equating to crossing your fingers and hoping for the best).
Our process level was largely driven by our clients who didn't have any interest in signing off specifications (for good reasons and bad), wanted people who understood their business and would fill in the gaps, and wanted to change their minds three times a day. As much as many of these factors infuriated the programmers in the UK we understood that they were never going to change.
This was possibly our biggest concern - we didn't feel we could come up with a process model that would work for all three groups involved (the clients, the UK based IT team and the Indian based outsource team).
So first thing is - work out what your process is and work out whether you honestly think you can make it work for all parties involved. It's easy to say "we're going to do agile" but how are you going to get that to work when one party is 1000 miles away? Alternatively if you want to go a solid waterfall route, is that realistic given your clients?
Second, understand the ingrained cultural differences within your teams.
My experience (and I obviously generalise here) is that programmers from the US and the UK willingly (sometimes too willingly) question authority and assumptions. Ask them to do something dumb and you're likely to find yourself being told that you've asked them to do something dumb in no uncertain terms and they'll then proceed to tell you what you really want.
That's not the norm globally. Many Indian developers I've worked with don't question things in the same way. That's not to say they aren't as bright, they just apply their intelligence to delivering what you've asked for, assuming that you had a good reason for doing so.
You can make a case for either of these being good / bad (I've lost count of the number of times I've heard developers question what they're told and say how things should be despite not understanding the basics of the industry they were working in), but the important thing is that they're different and they'll clash.
So the answer is likely to be that you're going to need to feel out the teams involved and, based on that, pick out ways of working that are comfortable for both of them.
Yes, get video conferencing set up, get each time to visit the other site (it makes a big difference) and where possible get people talking even when it's not strictly needed in the early stages, but most of all make the effort to understand the groups involved and design a dynamic that works for all of them - imposition of one world view on the other won't work.
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
If you are the lead programmer at a company and you need to complete a project that would require skills/knowledge that no one at the company currently has, what do you do?
I am not talking about something simple you can ask for help on stack-overflow for but for complex problems that you do not feel comfortable tackling and would take a significant amount of learning to be ready.
So at the point whats the best step to take?
Be honest with your management team, make sure they know. Don't ever try to mislead people about the scope of your knowledge - it doesn't impress them and only causes you problems.
Work with your team to evaluate your options - it may be possible to change technologies, or perhaps someone else in the organization can help mentor or support you. Changing course earlier on is easier and less expensive than later.
Adjust your project timeline to take into account the potential risk and delays caused by working beyond your core strengths. If you don't have enough knowledge to estimate the risk, be very conservative in the confidence factor of your estimates and timeline.
Look for an expert in the domain/technology and see if you can engage them either as a consultant or advisor on your project. Nothing makes a bigger difference than prior experience in a domain.
Take some time to try to create a simpe prototype or proof-of-concept in the domain/technology you will be working on. Look for possible issues that could emerge. Sometimes unexpected problems surface when you try to create a simple prototype - this can help steer the effort when working on the real thing.
See if the scope of your project can be scaled back. If you are already "behind the curve" the best way to improve your odds of success is tackling something smaller, rather than larger.
Seek out advise from people you trust. Especially people whose expertise and knowledge has some bearing on the problem or technology you're taking on. They may be able to give your more specific advise or ideas.
You have to take it outside the company to someone (person or consultancy) that can complete it. This means a contractor/consultant that will be with you for a temporary period of time. If possible have them work in house with your and your team and make part of their responsibility to train you.
You may have to explain to management that without this, the project could fail and will probably be late and over budget. Don't worry about outsourcing some projects - you and your team will still have lots of work.
Temporarily hire someone who has the expertise you're missing, and make sure they're prpared to transfer their knowledge to others in your team as well as work on the problem at hand. Be prepared to pay serious money; but if the problem really is complex, chances are you'd take much longer, get a much worse result, and pay more overall if you try to figure out out without any help.
First, +1 to Borgwardt, Oded, Bushkin. Great answers here. Now my two cents...
Your path forward should consider whether this is a skill/technology i.e. "capability" that your company needs to have internally. Depending on this, take the advice of either #Oded (Outsource) or #Michael Borgwardt (hire a contractor to do some knowledge transfer), or spend a lot of time (if you have it) and develop the capability on your own. For example, suppose you're going to interface with some purchased package that spits out magic numbers in some binary format. Hire a contractor to write the interface. Suppose your VP of fulfillment wants you to interface with a FedEx web service, and nobody at your company knows SOAP. And you know that more SOAP is coming, for all suppliers and partners. You'll need SOAP skills in-house, so get some training, do a prototype, and maybe bring in some outside help.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
Probably an easy one:
Are there any rules of thumb or pointers that could help recognise political requirements?
Let’s say one of stakeholders (your boss, a head of another department or an actual user) asks for a feature or particular characteristic of software being developed by yourself or your team. Is there a litmus test to determine whether requirement is political?
This question is really simple and is not about how to deal with political requirements or whether they are bad or good for software. How do you tell that whatever you have been asked to do is to pursue someone’s tacit or actually openly stated political agenda?
Will it really help you to know? I mean - if you're already embroiled in political games you'll know anyway. If you're not it isn't something you'll be able to use.
If you're going to have to implement the feature anyway I'd say just get on with it. Finding out that it's part of some management game will only demotivate you.
That said - if you're working on the sort of application that's so themware that you can't tell whether it's a real user feature or a political lever of some sort then it's probably a safe assumption that everything is political.
I would say that you should assume that all requirements are political.
If you are in a situation where more than one person is responsible for determining the set of features you implement, then every feature is effectively a negotiation between those people. That negotiation makes those features political.
However, even if there is only person deciding what features ship, there is still a pretty strong chance that those decisions are political. In any organization of reasonable size (say more than ten people), you are going to have politics. The politics in that situation will differ than the "design by committee situation". They will focus on currying the favor of the person who decides which features ship, rather than on "if you support my feature, I'll support yours" that exists in the committee scenario. That process, however, is still political.
I'm not trying to say that it's not possible to have a development environment free of politics. It is. However, I would say that to pull of it off that you need:
A small, tightly knit team
A boss that focuses on creating an environment that fosters creativity, and delegating creative ownership, rather than focusing on control over the creative process.
Smart, highly talented and creative people that share a strong sense of purpose and aesthetic values.
Missing any one of those things, you are doomed to a repetitive deluge of office politics.
The best idea is to find out what all the features are to be used for, i.e. find out not only how a feature is to be implemented, but also learn why it should be done. It really helps to know the background of the desired solution. It might even allow you to suggest an alternate feature set that might better suit your customer (maybe even play your own political game).
As long as there is anything you do not understand, do not do the project. It will only cause problems at some point.
Obviously it's a tricky question and much depends on your definition of the 'political'.
I would start with the simple question:
* Are the authors/originators of the requirement really using the software in question?
The requirement could come from your boss but it could be a translated valid requirement of the real user
Here are some I've seen:
It directly contradicts other requirements
It is clearly not feasible technically
It is "out in left field" ... it doesn't fit into the defined problem space
It contradicts common sense
BEWARE ... sometimes this results from your use-cases being wrong or incomplete. I've also purposely allowed some of these to proceed to development (e.g Eye-candy that sells the product but is useless or at least generally not used by the operators).
Use the SCRUM approach. Don't describe a feature as
"It should be doing this and that in the following way"
While the sentence above describes all you need to know to implement the feature, it does not justify the feature. My SCRUM book says features should be written down as a story. A story looks like this:
"As a <user-role>
I need a <functionality>
So that I get <business value>"
A feature that cannot be justified using such a story is an unjustified feature and thus there is no use to actually implement it.
E.g.
"As a visitor of a web portal I need a way to authenticate, so I can access my customer data, but nobody else can"
Now you don't only know that you need an authentication for your web portal, you also know who needs it (the visitors, basically everyone planing on using it more intensively) and you also know why it is needed, as it gives the user some value.
Other examples:
"As a passenger I need a list of all my booked journeys, so that I know when I'm going to travel where and won't lose the overview"
"As a book keeper, I'd like to have the sales tax being automatically printed to each bill based on customer data, so that I don't have to enter it manually each time I'm printing a bill"
If every feature needs to be written like that, you'll automatically see if a feature is for the customer, because it is really necessary, or just something your boss/company wants to have and also why they want to have it (what is the big picture behind it? Why are they doing it?).
The use of ambiguous words or phrases is often political.
However,
Never attribute to malice that which is adequately explained by stupidity.