Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
The structure of a FiM++ program requires that it end with the closing of a letter and the code author's name in a specific manner.
Dear Princess Celestia and Stack Exchange and String: A Sample:
...
Your faithful student, Southpaw Hare!
According to the language specification, the keyword "Your faithful student," (including the comma but not the following space) is used as an end tag for class definitions, and the following name is a comment with no syntactical effect.
The fact that the author is automatically included (if not strictly required) in every file makes me wonder if it can be used as a form of interpretable documentation akin to Java Docs. In other words, that other programs or editors would be able to parse out this name and use it in some manner.
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use "Your faithful students," for a plural form (or possibly "Yours faithful," or "Yours truly," for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
If creating a Java Docs methodology was considered, then what other features should be included? For one, a date seems common. Including some form of date comment at the top of the letter would probably look natural and not defy the design paradigm.
Since the language is new, unfamiliar to most, and honestly quite silly, here are a few resources to consider:
Original Release Announcement
October Followup
Sorry no one's given this any concern before me!
I'm heading development of the language, so I think I have a good grasp on the answer, here.
What is the requirement of such internal comment-based
documentation? Is there anything in this particular type
of syntax that would cause problems?
I've never considered an auto documentation technique like Javadoc, so there is no formal syntax for that. The compiler I'm working on completely discards comments, so it won't support it, but I'm sure it wouldn't be terribly hard.
Is the keyword sufficient to fit with the theme? It occurs to me
that the lack of ability to use "Your faithful students," for a
plural form (or possibly "Yours faithful," or "Yours truly," for an
ambiguous version) would make listing multiple authors look awkward
and unnatural (and looking like a natural pony-written letter is one
of the core design paradigms).
The idea of the author name on the last line was intended for the foremost author of the report, so multiple authors was never suggested before now. However, Your faithful students, would work nicely!
If creating a Java Docs methodology was considered, then what other
features should be included? For one, a date seems common. Including
some form of date comment at the top of the letter would probably
look natural and not defy the design paradigm.
Indeed! Perhaps something at the bottom of the report, like
(Written 2013-04-11)
Hope this help you. You have some great ideas, here, too! You should join the team!
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
This question does not appear to be about programming within the scope defined in the help center.
Closed 8 years ago.
Improve this question
I am writing a user manual and I have come to a discussion with a colleague. He says I cannot use the word "you" anywhere in the manual. Now I remember something about this at school but that was not for writing procedures. Also, doing some googling I observed that most tutorials where using it a lot. I would prefer using it but only if this is considered good practice. what do you think?
The alternatives that I know of are:
'You' (second person singular) - "You should put the plate on the table."
Imperative - "Put the plate on the table."
'We' (first person plural) - "We should put the plate on the table."
'The user' (third person singular) - "The user should put the plate on the table."
Passive - "The plate should be put on the table."
My own preferences are:
I prefer the imperative as the default mode, because it's the briefest (least verbiage).
I avoid the passive, and the first person plural.
I use the second person pronoun ("you") or a third person noun (e.g. "your system administrator") when I want an explicit subject instead of the imperative.
Some people believe that manuals should be written as if they were scientific papers. Others believe that technical accuracy and readability is more important. I'm of the latter persuasion - use "you" if it fits with your overall style, but be consistent in your usage - I find documents that switches between "you" and "we" are irritating (and it's a sin I've been guilty of myself).
Which is easier to understand?
Click the button. You will see a dialog box where you can type your name.
or
The action of clicking the button will cause the appearance of a dialog box allowing the possibility for the user to enter his or her name.
The first is much easier to grasp. (Using "you" can sometimes be sloppy, but that tends to be in cases where it's used as a substitute for "one", or "some people", or "people in general". It's fine to use it where you are actually referring to the person reading the text.)
If you want, you can avoid the
you-style by writing in the
passive/imperative style. You can
also try the 'we' approach, but that
might sound a bit childish. You're
doing nothing wrong with using you
though.
To avoid writing in the you-style,
use the passive/imperative style. The
we-approach might also work, though
it might sound a bit childish. There
is nothing wrong with using you
though.
We can avoid writing in the you-style
by employing the passive/imperative
style. Or we could use the
we-approach, though we might sound a
bit childish. One could try the one
approach, but risk sounding to
stiff-upper-lip and alienating the
reader. We don't mind using you once
in a while, though.
I myself do prefer the second line. A series of commands is easier to follow then a story in the you-form.
You should be writing explantions in the third person.
The Java streams model is a classic Decorator pattern example.
You should write instructions in the second person, but even then, it's still not a good idea to refer to the reader as "you".
Create a constructor that can initialize lists based on a given list of lists.
Now, how did you feel after I issued 2 commands to you, my reader?
Technical Writing Enforce the rule of using passive text only. which mean avoiding "you" will be a good idea to stay in the safe side. that's based on how i do it personally.
I would do what Google, Microsoft, Yahoo, etc do. Here's a random Help page from Google:
http://mail.google.com/support/bin/answer.py?hl=en&answer=8494
shows that "you" is being used. You can check how Microsoft writes their User Manual too.
As a side note, I wouldn't use "I" or "we".
I think if you are providing imperatives, such as "Open the door", or otherwise directly addressing the reader, then you should use "you" instead of making yourself more difficult to comprehend by talking about some abstract user.
Even in scientific papers, some of the most formal writing I can think of, it is debatable whether or not I, we and other first person language is permissible. As much as high school grammar teachers might like you to think otherwise, there is no universally appropriate scheme.
I would say just be careful. It could come across as too casual. If the intended audience is business-y, I would avoid it. However, if it's a home user scenario or the marketing is casual (think Southwest Airlines), I'd say go with it.
Just don't overuse. Then it becomes taxing on the reader.
Sample of how it's intended to be used?
It all depends on the tone and style of your writing. Formal approaches discourage the use of "you". Personally, I like
to use a style that is concise, to the point and relatively informal. I have no problem with the "you" word when used sparingly.
Avoid over usage as in:
When you want to start the application you have to enter your password and then you have to select the function you want to use.
From the Handbook of Technical Writing. 8th Edition (p. 262):
You can make sentences shorter by leaving out some articles(a, an, the), some pronouns (you, this, these), and some verbs, but such sentences may result in telegraphics style and be harder to understand.
So, I'd say it's OK to use you, but like Gilbert Le Blanc said in his comment, it's often better to write 'then click the button' instead of 'then you click the button'.
Impersonal form should be preferred. The use of 'you' would be too clear, and most of your clients will believe you are not professional. A clear manual will also reduce the need for post-sale customer support, and cause losses to the company.
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 4 years ago.
Improve this question
Stackoverflow users,
How do you keep yourself from creating large classes with large bodied methods. When deadlines are tight, you end up trying to hack things together and it ends up being a mess that needs refactoring.
One way is to start with test driven development and that lends itself to good class design as well as SRP (Single Responsibility Principle).
I also see developers double clicking on controls and typing out line after line in the event method that gets fired.
Any suggestions?
I guess it depends on your internal processes as much as anything.
In my company, we practise peer review, and all code that gets comitted must be 'buddied in' by another developer, who you have to explain your code to.
Time constraints are one thing, but if I review code that has heinously long classes, then I won't agree to the check-in.
It's hard to get used to at first, but at the end of the day, it's better for everyone.
Also, having a senior developer who is a champion for good class design, and is willing and able to give examples, helps tremendously.
Finally, we often do a coding 'show and tell' session where we get to show off our work to our peers, it behooves us not to do this with ugly code!
Use a tool like Resharper and the Extract Method command.
Long classes is one bad code smell of many possible.
Remedying overly large classes by creating lots of small ones may create its own problems. New engineers on your project may find it difficult to follow the flow of the code to work out what happens where. One artifact of this problem can be very tall call stacks, execution nesting through many small classes.
Another suggestion is to do only what is asked. Don't play the "What if" game and try to overdesign a solution. This has the "Keep it simple, stupid" idea behind it.
We're a java and maven shop, and one of the...I guess you could say forensic methods we use are the excellent FindBugs, PMD and javancss plugins. All will give warnings about excessive length in a method, and the cyclomatic complexity calculations can be very eye opening.
The single most important step for me to avoid large classes that often violate SRP was to use a simple dependency injection framework. This freed me from thinking too much about how to wire things together. I only use constructor injection to keep the design free from cycles. Tools like Resharper help to initialize fields from constructor arguments. This combination leads to a near zero overhead for creating and wiring up new classes, and implicitly encourages me to structure behavior in much more detail.
This all works best if data is kept separate from behavior, and your language supports constructs like events that can be used to decouple communication that flows in the downward direction of the dependency graph.
use some static code analysis tools in your automated builds and write/configure/use some rules so that for example someone has to write a justification when he/she breaks it..
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 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.
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 4 years ago.
Improve this question
An answer to a Stack Overflow question stated that a particular framework violated a plain and simple OOP rule: Single Responsibility Principle (SRP).
Is the Single Responsibility Principle really a rule of OOP?
My understanding of the definition of Object Orientated Programming is "a paradigm where objects and their behaviour are used to create software". This includes the following techniques: Encapsulation, Polymorphism & Inheritance.
Now don't get me wrong - I believe SRP to be the key to most good OO designs, but I feel there are cases where this principle can and should be broken (just like database normalization rules). I aggressively push the benefits of SRP, and the great majority of my code follows this principle.
But, is it a rule, and thus implies that it shouldn't be broken?
Very few rules, if any, in software development are without exception. Some people think there are no place for goto but they're wrong.
As far as OOP goes, there isn't a single definition of object-orientedness so depending on who you ask you'll get a different set of hard and soft principles, patterns, and practices.
The classic idea of OOP is that messages are sent to otherwise opaque objects and the objects interpret the message with knowledge of their own innards and then perform a function of some sort.
SRP is a software engineering principle that can apply to the role of a class, or a function, or a module. It contributes to the cohesion of something so that it behaves well put together without unrelated bits hanging off of it or having multiple roles that intertwine and complicate things.
Even with just one responsibilty, that can still range from a single function to a group of loosely related functions that are part of a common theme. As long as you're avoiding jury-rigging an element to take the responsibilty of something it wasn't primarily designed for or doing some other ad-hoc thing that dilute the simplicity of an object, then violate whatever principle you want.
But I find that it's easier to get SRP correct then to do something more elaborate that is just as robust.
None of these rules are laws. They are more guidelines and best practices. There are times when it doesn't make sense to follow "the rules" and you need to do what is best for your situation.
Don't be afraid to do what you think is right. You might actually come up with newer and better rules.
To quote Captain Barbossa:
"..And secondly, you must be a pirate for the pirate's code to apply and you're not.
And thirdly, the code is more what you'd call "guidelines" than actual rules...."
To quote Jack Sparrow & Gibbs.
"I thought you were supposed to keep to the code."
Mr. Gibbs: "We figured they were more actual guidelines. "
So clearly Pirates understand this pretty well.
The "rules" could be understood via the patterns movement as "Forces"
So there is a force trying to make the class have a single responsibility. (cohesion)
But there is also a force trying to keep the coupling to other classes down.
As with all design ( not just code) the answer is that it depends.
Ahh, I guess this pertains to an answer I gave. :)
As with most rules and laws, there are underlying motives by which these rules are relevant -- if the underlying motive is not present or applicable to your case, then you are free to bend/break the rules according to your own needs.
That being said, SRP is not a rule of OOP per se, but are considered best practices to create OOP applications that are both easily extensible and unit-testable.
Both are characteristics that I consider as of utmost importance in enterprise application development, where maintenance of existing applications occupies more time than new development does.
As many of the other posters have said, all rules are made to be broken.
That being said, I do think that SRP is one of the more important rules for writing good code. It's not specific to Object Oriented programming, but the "encapsulation" part of OOP is very hard to do right if the class does not have a single responsibility.
After all, how do you correctly and simply encapsulate a class with multiple responsibilities? Usually the answer is multiple interfaces and in many languages that can help quite a bit, but it's still confusing to the users of your class that it may apply in completely different ways in different situations.
SRP is just another expression of ISP :-) .
And the "P" means "principle" , not "rule" :D