Overclock.net › Forums › Software, Programming and Coding › Coding and Programming › Commenting a function in c++ best way?
New Posts  All Forums:Forum Nav:

Commenting a function in c++ best way?

post #1 of 15
Thread Starter 
Hello there, I will have to ask my teacher how he wants it but I am always getting points taken off for the way I comment my functions in the program.

I normally do it this way:
Code:
//Comment above function
void function(parameters)
{
     Code goes here.   //Comments behind what ever is needed.
}

Points taken off because it wasn't very direct... I just did an overview of the function

Then I tried:
Code:
void function(parameters)
{     //Comment here to make it more direct
     Code goes here. //Plus comments as needed.
}

Apparently no matter how I comment what the function is used for, I still get points deducted.....

Any one have any suggestions at least for the professional world?
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
post #2 of 15
I thought that IS the way you comment?
It's a computer
(15 items)
 
  
CPUMotherboardGraphicsGraphics
2500k 4.5ghz @1.35v Asrock Extreme 3 Gen 3 Asus GTX 470 725/1694 @1.025v EVGA GTS 450 900/1804 (PhysX) 
RAMHard DriveOptical DriveCooling
8gb Gskill 1600mhz 640gb, Seagate 1tb Spinpoint F3, Kingston 60gb SSD LG Combo Thermaltake SpinQ 
OSMonitorKeyboardPower
Win7 64bit Ultimate Acer X203H 1600x900 CM Storm Quickfire w/ Blues PC Power and Cooling 750watt Silencer MKII 
CaseMouseMouse Pad
Silverstone Raven RV02 Microsoft 1.1A Razer Goliathus 
  hide details  
Reply
It's a computer
(15 items)
 
  
CPUMotherboardGraphicsGraphics
2500k 4.5ghz @1.35v Asrock Extreme 3 Gen 3 Asus GTX 470 725/1694 @1.025v EVGA GTS 450 900/1804 (PhysX) 
RAMHard DriveOptical DriveCooling
8gb Gskill 1600mhz 640gb, Seagate 1tb Spinpoint F3, Kingston 60gb SSD LG Combo Thermaltake SpinQ 
OSMonitorKeyboardPower
Win7 64bit Ultimate Acer X203H 1600x900 CM Storm Quickfire w/ Blues PC Power and Cooling 750watt Silencer MKII 
CaseMouseMouse Pad
Silverstone Raven RV02 Microsoft 1.1A Razer Goliathus 
  hide details  
Reply
post #3 of 15
Thread Starter 
Like this time he took off points for "add function header", but if enough people think that I am doing it right then ill just complain to him.
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
post #4 of 15
Quote:
Originally Posted by KingAroan View Post

Hello there, I will have to ask my teacher how he wants it but I am always getting points taken off for the way I comment my functions in the program.
I normally do it this way:
Code:
//Comment above function
void function(parameters)
{
     Code goes here.   //Comments behind what ever is needed.
}
Points taken off because it wasn't very direct... I just did an overview of the function
Then I tried:
Code:
void function(parameters)
{     //Comment here to make it more direct
     Code goes here. //Plus comments as needed.
}
Apparently no matter how I comment what the function is used for, I still get points deducted.....
Any one have any suggestions at least for the professional world?

Coding teachers are extremely picky about how they want things, you should ask them how they wanted it. I anticipate its points off for what you are commenting as well.
Snowdevil
(16 items)
 
ASUS G750JM
(9 items)
 
 
CPUMotherboardGraphicsGraphics
[i7 4790K @ 4.4 GHz (1.186v)] [Asus Sabertooth Z97 Mark S] [nVidia Geforce GTX 1080] [nVidia Geforce GTX 1080] 
RAMHard DriveCoolingOS
[G.Skill 32GB DDR3 2133 MHz] [Crucial MX100 256GB] [Phanteks PH-TC12DX] [Win 10.1 Pro] 
MonitorMonitorKeyboardPower
[LG 29UM65 (2560x1080)] [QNIX Evo II LED (2560x1440)] [WASD v2 Tenkeyless] [NZXT Hale90 v2 ] 
CaseMouseMouse PadAudio
[ThermalTake GT10 Snow Edition] [Razer Mamba - Chroma] [Razer Kabuto] [Razer Man O' War] 
CPUMotherboardGraphicsRAM
i7 4770HQ Intel HM87 Express Chipset Geforce GTX 860M 8GB DDR3L 1600 MHz 
Hard DriveOptical DriveCoolingOS
Samsung SSD EVO DVD-RW Stock Windows 8.1 
Monitor
1920x1080 TN 
  hide details  
Reply
Snowdevil
(16 items)
 
ASUS G750JM
(9 items)
 
 
CPUMotherboardGraphicsGraphics
[i7 4790K @ 4.4 GHz (1.186v)] [Asus Sabertooth Z97 Mark S] [nVidia Geforce GTX 1080] [nVidia Geforce GTX 1080] 
RAMHard DriveCoolingOS
[G.Skill 32GB DDR3 2133 MHz] [Crucial MX100 256GB] [Phanteks PH-TC12DX] [Win 10.1 Pro] 
MonitorMonitorKeyboardPower
[LG 29UM65 (2560x1080)] [QNIX Evo II LED (2560x1440)] [WASD v2 Tenkeyless] [NZXT Hale90 v2 ] 
CaseMouseMouse PadAudio
[ThermalTake GT10 Snow Edition] [Razer Mamba - Chroma] [Razer Kabuto] [Razer Man O' War] 
CPUMotherboardGraphicsRAM
i7 4770HQ Intel HM87 Express Chipset Geforce GTX 860M 8GB DDR3L 1600 MHz 
Hard DriveOptical DriveCoolingOS
Samsung SSD EVO DVD-RW Stock Windows 8.1 
Monitor
1920x1080 TN 
  hide details  
Reply
post #5 of 15
Quote:
Originally Posted by KingAroan View Post

Like this time he took off points for "add function header", but if enough people think that I am doing it right then ill just complain to him.

A function header appears like this:
Code:
#include<iostream.h>

//Function Prototypes
int sum(int x, int y);

//A good choice of comment here is what the function does
int sum(int x, int y)
{
        int ans = 0;    //holds the answer that will be returned

        ans = x + y;    //calculate the sum

        return ans;    //return the answer
}

All of that is overkill, but when doing projects its not always a bad idea.
Snowdevil
(16 items)
 
ASUS G750JM
(9 items)
 
 
CPUMotherboardGraphicsGraphics
[i7 4790K @ 4.4 GHz (1.186v)] [Asus Sabertooth Z97 Mark S] [nVidia Geforce GTX 1080] [nVidia Geforce GTX 1080] 
RAMHard DriveCoolingOS
[G.Skill 32GB DDR3 2133 MHz] [Crucial MX100 256GB] [Phanteks PH-TC12DX] [Win 10.1 Pro] 
MonitorMonitorKeyboardPower
[LG 29UM65 (2560x1080)] [QNIX Evo II LED (2560x1440)] [WASD v2 Tenkeyless] [NZXT Hale90 v2 ] 
CaseMouseMouse PadAudio
[ThermalTake GT10 Snow Edition] [Razer Mamba - Chroma] [Razer Kabuto] [Razer Man O' War] 
CPUMotherboardGraphicsRAM
i7 4770HQ Intel HM87 Express Chipset Geforce GTX 860M 8GB DDR3L 1600 MHz 
Hard DriveOptical DriveCoolingOS
Samsung SSD EVO DVD-RW Stock Windows 8.1 
Monitor
1920x1080 TN 
  hide details  
Reply
Snowdevil
(16 items)
 
ASUS G750JM
(9 items)
 
 
CPUMotherboardGraphicsGraphics
[i7 4790K @ 4.4 GHz (1.186v)] [Asus Sabertooth Z97 Mark S] [nVidia Geforce GTX 1080] [nVidia Geforce GTX 1080] 
RAMHard DriveCoolingOS
[G.Skill 32GB DDR3 2133 MHz] [Crucial MX100 256GB] [Phanteks PH-TC12DX] [Win 10.1 Pro] 
MonitorMonitorKeyboardPower
[LG 29UM65 (2560x1080)] [QNIX Evo II LED (2560x1440)] [WASD v2 Tenkeyless] [NZXT Hale90 v2 ] 
CaseMouseMouse PadAudio
[ThermalTake GT10 Snow Edition] [Razer Mamba - Chroma] [Razer Kabuto] [Razer Man O' War] 
CPUMotherboardGraphicsRAM
i7 4770HQ Intel HM87 Express Chipset Geforce GTX 860M 8GB DDR3L 1600 MHz 
Hard DriveOptical DriveCoolingOS
Samsung SSD EVO DVD-RW Stock Windows 8.1 
Monitor
1920x1080 TN 
  hide details  
Reply
post #6 of 15
While yes you should have asked how it should have been done...he might have meant a function header such as...
Code:
/**
 * Locates a passed in word and occurrence in the data structure, printing out if the 
 * word is found and the word number associated with it. Also prints if the the word is not found.
 *
 * @param map the data structure mapping words to a list of its occurrences
 * @param command the vector with each element of the read in command as elements
 * 
 */
void locateCommand(unordered_map<string, vector<double>> &map, vector<string> &command);
Ol' Reliable
(14 items)
 
  
CPUMotherboardGraphicsRAM
2500k Gigabyte Z68X-UD3H-B3 Nvidia GTS 250 G Skill Ripjaws DDR3 
Hard DriveOptical DriveOSMonitor
Western Digital Black 640GB Lite On DVD-RW Win 7 64 Westinghouse 22" 
MonitorKeyboardPowerCase
Samsung 22" Coolermaster Storm QuickFire Rapid Corsair 650-TX Antec Sonata 
Mouse
Coolermaster Xornet 
  hide details  
Reply
Ol' Reliable
(14 items)
 
  
CPUMotherboardGraphicsRAM
2500k Gigabyte Z68X-UD3H-B3 Nvidia GTS 250 G Skill Ripjaws DDR3 
Hard DriveOptical DriveOSMonitor
Western Digital Black 640GB Lite On DVD-RW Win 7 64 Westinghouse 22" 
MonitorKeyboardPowerCase
Samsung 22" Coolermaster Storm QuickFire Rapid Corsair 650-TX Antec Sonata 
Mouse
Coolermaster Xornet 
  hide details  
Reply
post #7 of 15
Thread Starter 
RagingCain that is how I normally do it, and only use comments on the inside as needed.

Raffledoocious I think that header is needed for what you are doing, but I don't think I am in need of that complicated of a header just yet.
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
    
CPUMotherboardGraphicsRAM
2600K Sandy Bridge 5+Ghz ASUS P8P67 DELUXE x2 EVGA GTX 580 Water Cooled in SLI G.SKILL Ripjaws X Series 16GB 1600 
OSMonitorPowerCase
Duel Boot, Win 7 & Unbuntu 2 x 24in monitors Plus a 1080p projector CORSAIR Professional Series Corsair 600T 
  hide details  
Reply
post #8 of 15
Code:
/*
 * Brief: Returns the largest of two integers.
 *
 * @Param: first - One of the ints to compare.
 * @Param: second - One of the ints to compare.
 * @Return: Largest of 'first' and 'second' parameters.
 *
 * Author: John Smith
 */
int Largest(int first, int second) const
{
    if ( first >= second )
    {
        return first;
    }

    return second;
}
Foldatron
(17 items)
 
Mat
(10 items)
 
Work iMac
(9 items)
 
CPUMotherboardGraphicsGraphics
i7 950 EVGA x58 3-way SLI EVGA GTX 660ti GTX 275 
RAMHard DriveHard DriveHard Drive
3x2GB Corsair Dominator DDR3-1600 80GB Intel X25-M SSD 2TB WD Black 150GB WD Raptor 
Hard DriveOSMonitorKeyboard
2x 150GB WD V-raptor in RAID0 Win7 Home 64-bit OEM 55" LED 120hz 1080p Vizio MS Natural Ergonomic Keyboard 4000 
PowerCase
750W PC P&C Silencer CoolerMaster 690 
CPUGraphicsRAMHard Drive
Intel Core i5 2500S AMD 6770M 8GB (2x4GB) at 1333Mhz 1TB, 7200 rpm 
Optical DriveOSMonitorKeyboard
LG 8X Dual-Layer "SuperDrive" OS X Lion 27" iMac screen Mac wireless keyboard 
Mouse
Mac wireless mouse 
CPUGraphicsRAMHard Drive
i7-2600K AMD 6970M 1GB 16GB PC3-10600 DDR3 1TB 7200rpm 
Hard DriveOptical DriveOSMonitor
256GB SSD 8x DL "SuperDrive" OS X 10.7 Lion 27" 2560x1440 iMac display 
Monitor
27" Apple thunderbolt display 
  hide details  
Reply
Foldatron
(17 items)
 
Mat
(10 items)
 
Work iMac
(9 items)
 
CPUMotherboardGraphicsGraphics
i7 950 EVGA x58 3-way SLI EVGA GTX 660ti GTX 275 
RAMHard DriveHard DriveHard Drive
3x2GB Corsair Dominator DDR3-1600 80GB Intel X25-M SSD 2TB WD Black 150GB WD Raptor 
Hard DriveOSMonitorKeyboard
2x 150GB WD V-raptor in RAID0 Win7 Home 64-bit OEM 55" LED 120hz 1080p Vizio MS Natural Ergonomic Keyboard 4000 
PowerCase
750W PC P&C Silencer CoolerMaster 690 
CPUGraphicsRAMHard Drive
Intel Core i5 2500S AMD 6770M 8GB (2x4GB) at 1333Mhz 1TB, 7200 rpm 
Optical DriveOSMonitorKeyboard
LG 8X Dual-Layer "SuperDrive" OS X Lion 27" iMac screen Mac wireless keyboard 
Mouse
Mac wireless mouse 
CPUGraphicsRAMHard Drive
i7-2600K AMD 6970M 1GB 16GB PC3-10600 DDR3 1TB 7200rpm 
Hard DriveOptical DriveOSMonitor
256GB SSD 8x DL "SuperDrive" OS X 10.7 Lion 27" 2560x1440 iMac display 
Monitor
27" Apple thunderbolt display 
  hide details  
Reply
post #9 of 15
I do this as a job, and as part of a team of developers, code must be commented, but not overly commented.

As a rule of thumb, only comment when you need to explain what a complicated piece of code is doing. You have to assume that the person who is reading it (in this case, your teacher), knows how to program and will be able to follow simple things such as a for loop.

It's fine to explain what a function is doing too, but try to avoid comments to the right of code, in my opinion they just look ugly. It's better to have that extra line than have commented text hanging off your code. It makes it hard to follow.

For example:
Code:
- (void)helloWorld:(NSString *)string {
      return [NSString stringWithFormat:@"jNSK says %@", string];
}

Would require no comments as it's fairly straight forward and even someone with minimal coding experience could work out what it does.
Project 4
(13 items)
 
  
CPUMotherboardGraphicsRAM
i5 750 Lynnfield @ 4.4 GHz, 1.41v EVGA P55 SLi (132-LF-E655-KR) - A72 BIOS EVGA GeForce GTX 680 4GB G.Skill Ripjaws @ 9-9-9-24, 1.51V 
Hard DriveOptical DriveOSMonitor
80GB Intel X25-M SSD + 500GB WD + 2TB Samsung F3 Samsung Super Writemaster DVD+-R Windows 7 Ultimate Edition Samsung SyncMaster 2433 24" 
KeyboardPowerCaseMouse
Logitech G15 Corsair TX750 750W Corsair Obsidian 800D + Scythe Kaze Master Ace Razer Deathadder Respawn - Black 
Mouse Pad
Steelseries QcK Medium - Black 
  hide details  
Reply
Project 4
(13 items)
 
  
CPUMotherboardGraphicsRAM
i5 750 Lynnfield @ 4.4 GHz, 1.41v EVGA P55 SLi (132-LF-E655-KR) - A72 BIOS EVGA GeForce GTX 680 4GB G.Skill Ripjaws @ 9-9-9-24, 1.51V 
Hard DriveOptical DriveOSMonitor
80GB Intel X25-M SSD + 500GB WD + 2TB Samsung F3 Samsung Super Writemaster DVD+-R Windows 7 Ultimate Edition Samsung SyncMaster 2433 24" 
KeyboardPowerCaseMouse
Logitech G15 Corsair TX750 750W Corsair Obsidian 800D + Scythe Kaze Master Ace Razer Deathadder Respawn - Black 
Mouse Pad
Steelseries QcK Medium - Black 
  hide details  
Reply
post #10 of 15
Quote:
Originally Posted by jNSK View Post

I do this as a job, and as part of a team of developers, code must be commented, but not overly commented.
As a rule of thumb, only comment when you need to explain what a complicated piece of code is doing. You have to assume that the person who is reading it (in this case, your teacher), knows how to program and will be able to follow simple things such as a for loop.
It's fine to explain what a function is doing too, but try to avoid comments to the right of code, in my opinion they just look ugly. It's better to have that extra line than have commented text hanging off your code. It makes it hard to follow.
For example:
Code:
- (void)helloWorld:(NSString *)string {
      return [NSString stringWithFormat:@"jNSK says %@", string];
}
Would require no comments as it's fairly straight forward and even someone with minimal coding experience could work out what it does.

I'm not sure what language that is, but it looks like it has no return value, so why return a string? Or is the return value on the right-hand side of the function definition?
Foldatron
(17 items)
 
Mat
(10 items)
 
Work iMac
(9 items)
 
CPUMotherboardGraphicsGraphics
i7 950 EVGA x58 3-way SLI EVGA GTX 660ti GTX 275 
RAMHard DriveHard DriveHard Drive
3x2GB Corsair Dominator DDR3-1600 80GB Intel X25-M SSD 2TB WD Black 150GB WD Raptor 
Hard DriveOSMonitorKeyboard
2x 150GB WD V-raptor in RAID0 Win7 Home 64-bit OEM 55" LED 120hz 1080p Vizio MS Natural Ergonomic Keyboard 4000 
PowerCase
750W PC P&C Silencer CoolerMaster 690 
CPUGraphicsRAMHard Drive
Intel Core i5 2500S AMD 6770M 8GB (2x4GB) at 1333Mhz 1TB, 7200 rpm 
Optical DriveOSMonitorKeyboard
LG 8X Dual-Layer "SuperDrive" OS X Lion 27" iMac screen Mac wireless keyboard 
Mouse
Mac wireless mouse 
CPUGraphicsRAMHard Drive
i7-2600K AMD 6970M 1GB 16GB PC3-10600 DDR3 1TB 7200rpm 
Hard DriveOptical DriveOSMonitor
256GB SSD 8x DL "SuperDrive" OS X 10.7 Lion 27" 2560x1440 iMac display 
Monitor
27" Apple thunderbolt display 
  hide details  
Reply
Foldatron
(17 items)
 
Mat
(10 items)
 
Work iMac
(9 items)
 
CPUMotherboardGraphicsGraphics
i7 950 EVGA x58 3-way SLI EVGA GTX 660ti GTX 275 
RAMHard DriveHard DriveHard Drive
3x2GB Corsair Dominator DDR3-1600 80GB Intel X25-M SSD 2TB WD Black 150GB WD Raptor 
Hard DriveOSMonitorKeyboard
2x 150GB WD V-raptor in RAID0 Win7 Home 64-bit OEM 55" LED 120hz 1080p Vizio MS Natural Ergonomic Keyboard 4000 
PowerCase
750W PC P&C Silencer CoolerMaster 690 
CPUGraphicsRAMHard Drive
Intel Core i5 2500S AMD 6770M 8GB (2x4GB) at 1333Mhz 1TB, 7200 rpm 
Optical DriveOSMonitorKeyboard
LG 8X Dual-Layer "SuperDrive" OS X Lion 27" iMac screen Mac wireless keyboard 
Mouse
Mac wireless mouse 
CPUGraphicsRAMHard Drive
i7-2600K AMD 6970M 1GB 16GB PC3-10600 DDR3 1TB 7200rpm 
Hard DriveOptical DriveOSMonitor
256GB SSD 8x DL "SuperDrive" OS X 10.7 Lion 27" 2560x1440 iMac display 
Monitor
27" Apple thunderbolt display 
  hide details  
Reply
New Posts  All Forums:Forum Nav:
  Return Home
  Back to Forum: Coding and Programming
Overclock.net › Forums › Software, Programming and Coding › Coding and Programming › Commenting a function in c++ best way?