Modding in Style

RawrRawr Posts: 508 Seed
So it hit me. I was reading through some comments on a reddit post about big projects.
I'm paraphrasing here but - conforming to a standard style throughout the project is all about communication to other developers. In the worst case, reading code becomes a difficult task and even more so if each file uses a different style.

Take a deep breath. This is not about getting everyone to write the same way. Exhale.

The interesting part is that this is very analogous to spoken languages. There are tools and references about how to speak but people make up new words all the time and so languages are constantly morphing. Style is a little bit more well defined as your use of tone, volume, words, etc...

Now, let's bring this back to coding. I don't often hear people talk about exactly what coding style is. Mostly just that it's readable or not. What I'd like to do first is list some things that I think are style and people can say yes, no and/or add others. Actually I can only think of two atm so here they are: variable naming and indentation.

Second, because in spoken languages I could go talk to a professor or read a book, where and/or what tools/references do you know of when it comes to styling your code? I know in eclipse there's a way to auto format code. I don't know of any extensive lists of different coding styles though. What's your take on the subject?
Programmer, designer, artist.

Comments

  • ZakeZake Posts: 216 Seed
    I think those two are the big ones. From what I've seen, usually a language has a particular style convention that everyone kinda sticks to. Some are more rigid than others, but usually readability is key.

    For example, Python has you write variables like this: variable_name
    whereas Java is more like: variableName

    I think as far as the modding community goes: do as the Romans do. We are all adding to NK's code, so might as well follow their lead as far as conventions. I don't have access to it right now, but a few minutes through should reveal their naming conventions, capitalization, and indentation.

    And anyways, as long as the code works, it doesn't matter a terrible amount. Also: when in doubts, use comments. If you can explain in plain language what your code does, it'll make it way easier for you or future collaborators to understand and modify. :)
    I think more than I say and say more than I do, but I do more than I used to and plan to continue.
    TUG modder (at least in the ounce of free time that occasionally flits by)
  • Red AgliatorRed Agliator Posts: 307 Seed
    I've been trying to figure out NK's conventions for exactly the reasons Zake suggests.

    I've been noticing that NK is using (some) "Hungarian notation" (I think that's what it's called). The pieces that I've noticed:
    - object member/instance variables are usually called .m_variablename
    - accessors (when there are any) are usually Class:SetVariableName(newVariableValue) and Class:GetVariableName()
    - private functions that no other class should start with an underscore, as in Class:_DoSomethingInternal(...)

    (If you decide to look up what Hungarian notation is, "Microsoft" might also be a good search keyword: I'm told that that's where it originated. I imagine that there are lots of resources that outline those conventions.)

    I've also been trying to come up with conventions of my own, such as where I set the defaults for member variables (I'd like to have them in the same function for almost every class, so people know where to look).

    But that's less because it's a great idea, and more because I like to do things in an orderly fashion. I also separate my m&ms by color before eating them, so I think you get the idea.
  • nocarenocare Posts: 92
    edited June 2015
    I too like to somewhat conform to a framework/culture I work in, but not always. I keep my own forms of certain things when able and my stance on anything in particular does change with time.

    When it boils down to it, many things are preference. Whether or not they perform faster, are easier to read, etc. Attempting to be consistent in one particular project or a collection of interacting projects is always a good idea.

    I tend to not like overly descriptive variables and hungarian notation. It's useful and "scientific" which can be a good thing, but it can also be a bad one because you can end up with overly complex names like "NoStanceRangedWeapon" that don't really clearly define what the object actually is without additional knowledge of the platform.

    One of the things I've been focusing on a lot lately is trying to write code as if I could speak it. This isn't always possible, easy, or worth spending time on, but it is something i've picked up from laravel I have been tinkering with.

    Some pseudocode kind of demonstrating what I am talking about here. It becomes very obvious what is going on in this line when you've put time into doing this, and doing it a lot. I did omit some variables and this won't run in tug as-is, but I hope it makes sense what I was going for.

    local myItem = m_player:Get("InventorySlot", 1) myItem:MatchOrientation(playerFacing):NKSetLinearVelocity(m_force) myItem:DropInWorld(m_here):NKEnableScriptProcessing(true)


    I do tend to value being able to understand (myself and others) code over how speedy or concise it is. Comments are great, but they are meant to exist to summarize, teach and to explain why you did something. If you have to translate every line of code to english, I feel there is a problem to be solved there.

    A very interesting talk I listened to a while back: http://www.infoq.com/presentations/7-ineffective-coding-habits.This site in general has a lot of really good presentations. Some are philosophy and others I about specific technology or problems and I do recommend giving it a browse.

    Final thoughts: Do whatever you are comfortable with and always seek out ways you might be able to improve your style. Try to be consistent when working with groups, or at least not wildly different. Even with the same conventions, people approach problems in different ways and can confuse each other and that is just how it is and why comments explaining why you do things one way help a lot.
  • UFIOESUFIOES Posts: 42 Seed
    edited June 2015
    I prefer naming methods/functions in camelCase, although that is mostly a habit I picked up from Java.

    I also indent empty lines, which I think helps speed up coding, as pressing tab 5 times or isn't entirely expedient.
    nocare said:

    I tend to not like overly descriptive variables and Hungarian notation. It's useful and "scientific" which can be a good thing, but it can also be a bad thing because you can end up with overly complex names like "NoStanceRangedWeapon" that don't really clearly define what the object actually is without additional knowledge of the platform.

    I am a believer in descriptive and concise variable names. While some believe that they can take to long to type out, I think that this problem is solved by most IDE's use of "auto-complete"
    Although I agree that knowledge of the platform is necessary to understand any code, good names can help someone gain that initial understanding of the platform.

    I will admit that I do not understand why TUG's ivars are prefixed with "m_" especially when, most of the time, the "m_" is preceded by self.m_something

    Do you think that it is more important than usual for TUG to be written very carefully due to the fact that most modders will read through their code for examples and subsequently imitate their coding style?

    Edit: Sorry. I am happy to revise my post if it offended you in any way.
  • RawrRawr Posts: 508 Seed
    edited June 2015
    Communism, kittens, moral imperatives, the world... I started this thread about coding style within mods.

    I don't see any reasonable explanation as to why these ideas would be pulled into the subject. Have I overlooked something?

    Regardless, leave your negative, backhanded, blaming comments out of further discussion. They are not called for.

    Edit: thank you for the revision. I felt it would've been the beginning of a non-constructive tangent.
    Programmer, designer, artist.
  • UFIOESUFIOES Posts: 42 Seed
    Sorry
  • RawrRawr Posts: 508 Seed
    edited June 2015
    On imitation:
    I've liked some of TUG's style but I haven't gone along with everything yet. For example, I am not fond of the "m_" before member variables. Maybe further on down the track I'll find a good reason for it but we'll see.

    When I first made the post I realized some things. Firstly, that I don't have a solid basis for identifying exactly what the coding style components are. I mentioned two and asked about any resources people knew of. Second, that I saw there was value in styling code in a similar fashion to other developers within a domain. Here, that'd be us modders but then again I knew that conformity is not always my style and this was likely the case for other modders too. I drew the analogy to language because neither those who consistently conform nor those who consistently diverge are in the wrong. It is not a complete science... yet.
    Programmer, designer, artist.
  • RawrRawr Posts: 508 Seed
    Is coding style all about a signal to noise ratio or would describe it as such leave something within it undefined?
    Programmer, designer, artist.
  • Red AgliatorRed Agliator Posts: 307 Seed
    edited June 2015
    Rawr said:

    I mentioned two and asked about any resources people knew of.

    I don't have any specific resources to recommend. I've always learned about coding style as a side thing while working on projects. For example, good tutorials usually have a specific style, which I tend to pick up while I'm on that project. I've learned a lot while Apple programming, too -- their developer docs usually go so far as to recommend style elements. And again, I try those out while I'm working on a related project.

    I suspect most people who work in teams pick up coding style elements that way: either because certain things are required, or because various people come to agree that certain aspects would be helpful for communication.
    Rawr said:

    Is coding style all about a signal to noise ratio or would describe it as such leave something within it undefined?

    Could you say this a different way? I'm not sure what you mean by signal to noise ratio. Are you asking how strict programming style definitions tend to be?

  • RawrRawr Posts: 508 Seed
    edited June 2015
    Ex. I could name a variable as m_int_Name, mInt_Name or something like that. Adding in extra information in order to try signal the important things. Except, what if my variable name was myInt? adding in that extra information creates more noise than signal - m_int_myInt.

    It's a bit of a cod example but it's to make the point.
    Programmer, designer, artist.
  • mercormercor Posts: 64 Seed
    This is an awesome thread!

    I think this is super important subject in any bigger collaborative coding effort. Which I think TUG modding fits perfectly well.

    I come from javascript background, where there's available a lot of coding conventions / style guides made by community. I think it really helps improve the code quality a lot, if a project picks one, and clearly states which styles it is using.

    The important thing with coding conventions, is that they are conventions, not rules. Meaning they are something that are used, to the best effort of everyone involved in that project. And time to time, people mix the conventions and write bad code. That happens. Fortunately refactoring code later is easy.

    It would be pretty cool, if nerd kingdom would make a lua coding conventions doc of their own available. So that it would be easier for mods to keep to same conventions, if they so want to do.

    But then again, coding conventions should always be a project specific thing. Meaning, every mod should in the end decide themselves what conventions they want to use.

    Example Coding Convention doc:

    With short googling, I found this one lua coding conventions documentation by Olivine Labs that looks like a worth having look at.

    I don't have that much experience with lua that I could say about whether or not the conventions specified in the document are good ones. For example, I don't know why they favor snake_case and PascalCase in names.

    But I like the way the document is structured. It clearly shows what is, according to it, a good convention and what is a bad thing to do. Although, one thing that they seem to be missing for large part, is describing why those things are good or bad.

    They seem to support some things that I personally don't like in other languages, but that might be just because lua doesn't currently support better means to do those things. But for many parts, they seem to have conventions worth trying.

    But well, even though I don't totally agree with everything in that documentation, it seems like a nice place to start for picking the best parts in to your own coding conventions.

    .editorconfig:

    Related to this, I found a nice tool called editorconfig for sharing your whitespace rules (and some other rules) between different editors (and users). So far I haven't gotten it to work with atom 1.0, even though there's a plugin for it. But the idea sounds pretty good.

    In theory, what it does: you can add simple rules, for programming language independent stuff like whitespaces, to your project. Then if your editor supports .editorconfig, it should automatically set the correct rules on in that projects folder. A lot of big IDEs seem to support it by default, and it seems there are plugins made for a lot of IDEs that don't have native support.

    So it doesn't do you linting or similar language specific stuff, but just the ability to declare rules for spacing and for the final new line, sounds pretty good.
    Modder in making. Point of Interest mod - Now with GUI

    twitter: @mercorinred
Sign In or Register to comment.