7

As the title states it, I would like to get some suggestions about putting knowledge into action.

We have many additional requirements that concern: coding practices feature development (all of them or only a subset), process, etc. The problem is that we have problems with introducing those practices into new projects and I want to help developers and reviewers to remember about it, but I don't want them to have everything just in theirs heads, but rather in some kind of a database that they can use easily.

The list of practices is already defined in Excel. I would like all team members to apply these practices in their work but I don't know how make those information easy to find. When developer starts working on a feature he should be able to easily find all practices that he should use in these feature.

To be clear with what I mean, I'm showing some examples of information we have to apply:

  • (new design request) every feature must output logs (and it must not contain any sensitive data);

  • (new design request) every feature has to have a flag in the configuration that allows to disable it;

  • (good practice) always update docs when feature is ready;

  • (retrospective feedback) QA must test only on release package (not in debug mode);

  • (retrospective feedback) make stress tests for every new feature implemented;

  • (lead's task) write release notes after each sprint that includes tasks completed and open bugs;

  • (design usage) every event from "ABCStoreManager" must be disconnected after being invoked;

  • (design usage) try-catch every event.Invoke() call;

I thought for a while about a wiki, but it's no good, because it doesn't support tagging/categories or querying and I'm afraid that everybody would ignore it (people must know exactly where to look).

My question can be summed up as how can I improve communication to our developers about the required development methodologies and practices listed above in an easy way?

Remarks:

  • this question is not about security issues or code smells per-se;

  • I'm not looking for any heavy process (like RUP) or any process for that matter, which forces you to go step by step. Preferably I am looking for an agile approach

  • Daniel Figueroa has suggested adding additional requirements to the "definition of done". And it seems like a good way. But the problem is that some features have, for instance, 20 additional requirements ("all GUI features"), some 10 ("all server requests"), etc. I would like to have this stuff aggregated in a one place and just use links ("see: 'GUI feature' ");

5
  • Are you doing code reviews? Feb 16, 2014 at 22:17
  • I don't know how to provide you with an answer, but here are some quick points: 1) Asking the Tester to go through logs to find sensitive data is a bit much. This task will take an ever-increasing amount of time as you keep adding features to the system. 2) The point about ABCStoreManager is a code smell. If usage of a class requires the dev to be aware of undiscoverable setup/teardown steps then it's probably not well designed. The class should be responsible for managing its own state -- it is not a concern of its consumers. 3) Doesn't Scrum/agile advocate self-documenting code?
    – MetaFight
    Feb 16, 2014 at 22:25
  • @RobertHarvey - yes, not always, but yes. But these detect problems with design, clean code, etc. It would be great if reviewer could check for spec requirements as well - but it would be cumbersome for him to the Excel to check for additional requirements.
    – andrew.fox
    Feb 17, 2014 at 5:29
  • @Meta:I don't understand your point #2. The consumers are the ones who know whether they care about receiving events or not, so the consumer should be responsible for connecting and disconnecting from events when they want to or no longer want to receive them. The ABCStoreManager, as a publisher, simply posts events as they occur; oblivious to who is listening for the events. If there is anything to complain about it is that there is a Manager class, that's the real problem.
    – Dunk
    Feb 17, 2014 at 16:28
  • 1
    This is a really good question. IME, it turns out to just be passed down knowledge that is captured in reviews, as each reviewer has stuff in their mind that has bitten them in the past. Unfortunately, IME, writing stuff down in standards docs or creating checklists doesn't really help because as the list grows people gloss over the details as it becomes too much to take in for people. Too much, is just as bad as not enough. This is similar to coding standards, without some form of automation, it doesn't really happen reliably.
    – Dunk
    Feb 17, 2014 at 16:39

2 Answers 2

3

Okay so here is what I believe.

When it comes to your example with the logs I think you actually have the answer in your list. What it boils down to is in the definition of done. If the devs are printing sensitive data to the logs and the testers are supposed to check that no sensitive data makes it to the logs, then clearly that feature isn't done, which means that the tester should put that feature back to In progress or whatever you guys are doing to keep track of development.

The same goes for everything that has to do with the actual code, now I'm not promoting a view that the testers should teach the developers. But they should work as a guard that the implementation is up to par with your standards. Any developer worth his/her salt should quickly take it to heart if every time they create a new feature it gets sent back because they didn't properly adhere to some of your rules.

Another thing I think is really important is what @Robert Harvey put in the comments field, code reviewing. That could be anything from pair-programming to something more formal. If a piece of code has only touched one pair of eyes I strongly believe something must be done. Such a simple thing as a high level description of what the code does while showing the actual code has made me blush several times because I've found problems or things I've missed several times. And usually it's just dumb mistakes.

So to recap:

  • One responsibility of the testers are to check that the devs are following rules.
  • Don't let devs act as lone-wolfs, should be a social activity (I don't always like it but it's true).
  • Have a clear definition of done, and don't let the implementer be the only one that says it's done.

I think this is a question about culture not about tools.

4
  • I agree with what you're saying. (1) The issues is, should I add "practice requirements" (LLs, GPs, etc) into "definition of done" of every task? Big duplication. (2) How to pass to the tester what are additional requirements to check for? Some of additional requirements apply for 70% of the features, some for 10%.
    – andrew.fox
    Feb 17, 2014 at 5:35
  • 1
    @andrew.fox - this project warrants "Big Duplication" when it comes to logging and sensitive data requirements. Writing it in every task is the least of your worries.
    – JeffO
    Feb 17, 2014 at 14:09
  • 1
    I don't think the question is really focused on the "sensitive data" issue as there is a more generic issue being asked in the OP question. However, I wonder if the developers would really be logging "sensitive data" if they were told not to put sensitive data in the logs AND (BIG AND) they were aware of what data was considered "Sensitive". If "Sensitive" is kind of nebulous then it should be part of testing and review by a more knowledgeable person on what "Sensitive" means. Otherwise, if "Sensitive" is clear-cut then developer competency seems to be a bigger part of the problem.
    – Dunk
    Feb 17, 2014 at 16:49
  • @andrew.fox 1) Preferably it should be implicit that a task is not done until it's documented and tested and it is working as expected (i.e in this case not printing sensitive data). But if it isn't then it should be explicit, and a part of the definition of done. 2) If the testers aren't passed information about what is expected of a feature to be considered done, how are they expected to be able to do their job? Feb 17, 2014 at 22:06
1

We used a wiki at a previous job, and it worked well. Any changes were publicised to the developers, and the team leads discussed it at regular intervals.

It seems to be that in in your list, you have both programming best practice and process definitions. I'd suggest first writing up the process by which you develop software. Then you can add sub-polices regarding best practice or language-specific guidelines. The main policy should refer to it and make it clear that developers should follow the style practice guidelines unless there is good reason not too.

Note that I'm not advocating writing pages and pages of docs - just enough to make it clear what a dev is supposed to do at any particular point in a project. If you can't easily summarise it, I'd suggest the current process itself is vague.

5
  • and a +1 for wiki rather than Excel. Accessibility needs to be super-easy, waiting a minute or two for Excel to start up so you can read a list of "things to remember" will kill your enthusiasm.
    – gbjbaanb
    Feb 24, 2014 at 15:15
  • As I wrote I'd thought about it. But the wiki idea was dropped due to lack of support of tagging or categories. E.g. how to browse for all tasks for which a Team Leader is responsible.
    – andrew.fox
    Feb 24, 2014 at 17:28
  • We weren't using the best wiki software, but we use a reasonably simple page hierarchy, and we had search :-) Feb 24, 2014 at 17:36
  • @andrew.fox: A shared OneNote can go a long way. I've worked at a place where the shared onenote (which is searchable) was the first, and often last, place to look for answers. Most people had it open at all times. There were 2-3 main people who updated everything, all the time, and it was great having them. Feb 24, 2014 at 20:47
  • @Steve Evers - yeah, but you have to have a license :)
    – andrew.fox
    Feb 25, 2014 at 9:55

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.