Cogito, ergo sum

Legacy:Guidelines On General Style

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to: navigation, search

This page defines (and debates) general style for the project. See also:

Writing Conventions[edit]

Avoid abbreviations. Their meaning may be clear to you, but abbreviations have the inherent risk of being ambiguous and confusing not only newbies. Very common acronyms like HUD and BSP have their own pages – link to them.

Text formatting[edit]

Some simple guidelines:

  • use '' and ''' wiki-style formatting instead of B and I tags. Use ''''' if you really must, but ask yourself: why does it need to stand out so much?
  • don't use the U tags, it can get confused with links.
  • don't use font colours.

And some reasons for them:

In general, ask yourself the above question: why does it need to stand out so much? It's up to the reader to give your article his/her attention, not up to you to grab it. If they are reading your page, then they want to learn about what you have written.

Don't overuse emphasis. It loses its effect and makes articles hard to read. Some things will stand out of their own accord, if you use the agree formatting conventions:

  • class names and window names (because they're a link – or should be)
  • menu commands and properties (because the -> glyph is distinctive)

A fact that there's no escaping is that most of the procedures described on the site involve many complex steps. Readers of this site are aware of this, and will read carefully – if they don't they'll soon learn.

Consider alternatives to lots of bolding:

  • a bullet list
  • a table, for example if an actor needs lots of properties setting

Technical formatting[edit]

Class Pages Layout[edit]

Class pages on the Wiki have this format at the head:

<wiki>@@UT/UT2003 :: Actor >> foo >> bar (Package: package name)

Some clever description of the class.

Properties[edit]

Interesting Group[edit]

string Property1 [replicated to clients]
That's some mighty interesting property.
Pawn (UT) Property2 
That one might be less important.
class<Actor> Property3 [const] 
Not changable but still not neglectable.

Not-so-interesting Group[edit]

int anArray[4] 
Dunno.

Structs[edit]

SpecialStruct[edit]

int X
int Y 
Where am I?
float Range 
How far is it?

Enums[edit]

EThisAndThat[edit]

TAT_One 
First enum value.
TAT_Two 
...
TAT_Three 
etc.

Delegates[edit]

bool OnStupidIdea (coerce string Description) 
Called whenever the author has a stupid idea. (Like now :-))

Methods[edit]

Native Function[edit]

float SomeNativeFunction (Class<Canvas> C) [static, final] 
Whatever this one does.

Events[edit]

PostBeginDelete ( ) [simulated] 
Panic and cry.

Other Functions[edit]

Pawn (UT) NextVictim (bool bHungry, optional bool bAngry) 
Well, yeah.

Known Subclasses[edit]

  • anything that's left

Category:Legacy Class (UT)
Category:Legacy Class (UT2003)

</wiki>

Question: Should we farm out the above to a separate template class page? Would it be clearer?

Comments on a better layout are welcome, but we should stick to one layout throughout the site to to keep the confusion at a minimum level.

Uncommon: What about having a way of coloring variable and function declarations so that the names stand out more? I've been leaving out the types and parameters because I think having all that stuff makes it harder to read. Maybe leave the name in the normal color and make the rest gray.

Tarquin: Could be done, I suppose, by searching for keywords within a ;: wiki tag. Wookee scares me though :(

More: Guidelines On Technical Names

Component by componenent, this is:

Class box[edit]

{game} :: Actor >> ... >> ... >> ThisClass (package)

property lists[edit]

type Name (variable modifiers or replication comments) 
description

Class Boxes and Property Settings[edit]

Giving a list of properties the reader should set on specific actors. No set standard as such, though you might want to use something like:

Set the following properties:

  • Trigger A : Events -> Tag = 'foo'
  • Monster B : Movement -> Something = 567

Suggestions[edit]

Search Keywords[edit]

Suggestion: adding keywords to some pages so they can be found by the search function?

Related Topics[edit]