Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
When I fix a bug I mention briefly what was the issue and in which revision its fixed. But this way nobody would know how much tricky the issue was and how much effort went in analysis and findings.
What is the best practice for a developer to show such things to higher management to get noticed?
To put bug analysis in there is a good practice, for the reasons you mentioned (just avoid being overly verbose).
This way, people reading it (including your future self) would know how much tricky the issue was and how much effort went in analysis and findings. Also, this way simplifies maintenance in the case when further changes are required related to your fix, because one could read bug report and understand why things were changed one or another way.
Just don't expect this to directly make you get noticed by higher management, because this is a different matter, a matter of workplace visibility, and this would require other skills and approaches. For the purpose of visibility, details you put into bug reports play only auxiliary, secondary role, allowing you to quickly find and get these details when necessary. Being capable to quickly pull out a clear explanation for tricky technical matters may give one a certain edge visibility wise, but it does not guarantee a major advantage.
To put fix code (except for snippets that are relevant in your analysis) into a bug report is another matter, typically a bad practice, as it is expected to be in VCS.
Good issue trackers integrated with VCS can even automatically refer readers to changes related to the fix. For an example on how this could be, take a look on Integrating JIRA with Subversion:
JIRA's Subversion integration lets you see Subversion commit information relevant to each issue. Subversion integration can be implemented either by using Atlassian FishEye or the Subversion add-on... both solutions allow you to link JIRA to related code changes in Subversion.
Commits will appear in this tab if the commit log mentions the issue key ('TEST-3' above)...
"What is the best practice for a developer to show such things to higher management to get noticed?"
In my experience, higher management usually doesn't have the capacity to understand what you would have typed anyway. The further away from development you get, the less they deeply understand. If you do have higher management that is competent to your level, then simply talk to them. I've found that higher management geeks are still geeks and love talking about geeky hacks.
If you are truly interested in self-promotion, keep a log book of all your successes, along with how difficult they were. When review time comes around, you will be prepared with specific examples.
"As a software developer, is it good practice to put bug analysis and fix code in bug report?"
Bug analysis? Yes. Other developers need to see how you fixed the bug if they run across a similar problem, especially because pulling a diff and figuring it out can be tedious (if you are leaving the old code commented and describing the entire fix in a comment, shame on you).
Fix code? Absolutely not. DRY is not only within the code base, but within artifacts and process information: tie the checkin to the bug/case number either via tooling or the checkin comments, and if they want to see how you fixed it, it should be easily retrievable. Think of it this way: if they have the capacity to view and understand code and really understand the complexity of your work, then they probably have access to source control anyway.
Every place I've worked, we had at least two mechanisms for documenting bug fixes. A changelog edited by the developer, and the commit log also edited by the developer. The latter is typically just entered as a "message" when you commit the file to source control.
I always follow two principles when fixing a bug and committing it.
First, I always enter a brief summary of the bug, the fix, and the module it's applied to in the changelog. Always keep in mind your audience for this text: everybody. From the other developers and yourself, to support and QA, the sales staff and even the customers. Everybody needs to understand your log entry. That means that to a certain extent you're writing to the lowest common denominator, but you still have to describe the bug and the fix in such a way so that the explanation is clear and not embarrassing to the company. Remember, the customers might read this. And be brief. I target less than 10 words.
Second, I add detailed information about the problem and the fix in the commit log. The audience for this text is very narrow: yourself and other developers. Get as technical and detailed as is useful. Since this is being committed to source control, it will be there forever in the form of a history log.
Also since the change is being comitted to source control, recall that source control itself is a change documentation tool that can and is used to explain technical changes. If a developer sees something in the change log that they want very specific details about, they will check the source control history and compare your change to the old version side-by-side. I do this all the time. This means you do not need to be verbose in any of your log entries about the what you changed. My verbose log entries are rare, and they are always focused on the why. The again, the why should also be documented in the code as comments.
Now, as to your question:
What is the best practice for a developer to show such things to higher management to get noticed?
Emphasis mine. Let's talk about this. Coming from the perspective of higher management, I'm going to suggest that you don't. You will just come off as a whiney blowhard, always complaining about how hard your job is and how awesome you are. At least it could be perceived that way. It reflects badly on you to bloviate. Stick to the facts, get your work done, and kick ass. You will get noticed through the quality of your work. If you don't, move on.
I have been working on a project, where it was "standard" to put code of a bug fixes in Word file. We were a team of three developers and a manager and manager was incapable of using version control software to do exactly what it was posted in Word file. The thing died throughout project development, as us developers didn't see the value and forgot to update files. I would not go down this path again.
However, there is nothing wrong with bug analysis report. But don't over do it. If there is no crisis and bug didn't cause business damage, it is just a waste of time.
It makes sense to put a decent amount of information in there, but whether it will help you "get noticed" is debatable.
It might be one tiny thing in a list of many other things that mark you down as a conscientious developer which management may pay attention to.
Management doesn't see it that way.
An employee who solves a problem in a short time will always be considered more valuable than one who solves a problem in a longer time. It doesn't matter if one problem was way harder to understand and way more important for the project - you can usually assume that your higher-ups don't understand the technical issues at stake, and they will assume that every underling exaggerates the difficulty of whatever they are given, Scotty-from-Star-Trek-style.
What you should do to prove your worth is to establish formal metrics that are applied to your workflow and excel at them. For instance, a measurement that managers seem to like is a rate of turnover (story points fulfilled, number of issues resolved).
