[Facelift] HttpFoundation (components/http_foundation/introduction.rst and related sections) #2395

Closed
weaverryan opened this Issue Mar 30, 2013 · 5 comments

Comments

Projects
None yet
3 participants
@weaverryan
Member

weaverryan commented Mar 30, 2013

This ticket is about re-reading this document and giving it a facelift. No matter who you are, you have a role to play in this.

How this works:

If you read this document and find some changes, you can either comment here or (even better) create a pull request. After various people have reviewed this chapter, we'll close this issue.

What to do

Well, that depends on who you are :)

If you're newer to Symfony

Read the entry and code along with it.
a) Are there inaccuracies - code that doesn't work?
b) Are there parts that just don't understand very well?
c) Are there details that aren't explained enough?
d) Is there language that's confusing?
e) Did you fall asleep while reading it? If so, good morning! Why was it so boring?
f) Are there inconsistencies between sections?

If you know Symfony pretty darn well (or want a challenge)!

a) Are there inconsistencies between sections?
b) Do you spot anything that can be done better?
c) Are we following best practices?
d) Are there sections that are too advanced or details that should be moved into a new section to keep this readable?
e) Should some details here belong somewhere else? Like in the component documentation?
f) Are there places where we can link to other areas in the documentation to help the learner cross reference?

@joelclermont

This comment has been minimized.

Show comment Hide comment
@joelclermont

joelclermont Mar 30, 2013

Contributor

Going to make some comments in this thread as I read through the docs.

http://symfony.com/doc/2.1/components/http_foundation/introduction.html#request

"almost equivalent" - should we describe the differences? should we mention the behavior of createFromGlobals() when it comes to the PUT, PATCH and DELETE verbs?

Contributor

joelclermont commented Mar 30, 2013

Going to make some comments in this thread as I read through the docs.

http://symfony.com/doc/2.1/components/http_foundation/introduction.html#request

"almost equivalent" - should we describe the differences? should we mention the behavior of createFromGlobals() when it comes to the PUT, PATCH and DELETE verbs?

@joelclermont

This comment has been minimized.

Show comment Hide comment
@joelclermont

joelclermont Mar 30, 2013

Contributor

I'm seeing variation on whether or not to capitalize (or backtick) words like request/Request or session/Session. Is there some standard on this? From my perspective, unless it's talking about working with that class or an object of that class, we should probably use the lower-cased request or session. Thoughts?

Contributor

joelclermont commented Mar 30, 2013

I'm seeing variation on whether or not to capitalize (or backtick) words like request/Request or session/Session. Is there some standard on this? From my perspective, unless it's talking about working with that class or an object of that class, we should probably use the lower-cased request or session. Thoughts?

@wouterj

This comment has been minimized.

Show comment Hide comment
@wouterj

wouterj Mar 31, 2013

Member

Yes, I always use captialized words to indicate class names (e.g. Closure) and lower case names for all other things (e.g. callable).

Member

wouterj commented Mar 31, 2013

Yes, I always use captialized words to indicate class names (e.g. Closure) and lower case names for all other things (e.g. callable).

@joelclermont

This comment has been minimized.

Show comment Hide comment
@joelclermont

joelclermont Mar 31, 2013

Contributor

But when you use the capitalized class name, do you also surround it with double back ticks, or what is the rule for that?

Could you review some of my changes from the attached PR and let me know if I'm on the right track? Thanks.

Contributor

joelclermont commented Mar 31, 2013

But when you use the capitalized class name, do you also surround it with double back ticks, or what is the rule for that?

Could you review some of my changes from the attached PR and let me know if I'm on the right track? Thanks.

@wouterj

This comment has been minimized.

Show comment Hide comment
@wouterj

wouterj Mar 31, 2013

Member

We don't have many rules about that (I started writing our standards a couple months ago). In most cases, I prefer to use literals (double backticks) for class names.

I reviewed your PR and I think it's correct, except from my comment

Member

wouterj commented Mar 31, 2013

We don't have many rules about that (I started writing our standards a couple months ago). In most cases, I prefer to use literals (double backticks) for class names.

I reviewed your PR and I think it's correct, except from my comment

@wouterj wouterj closed this Dec 23, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment